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#0: About Macintosh Technica! Notes 


Written by: Scott Knaster February 10, 1985 
Modified by: Jim Friedlander July 21, 1986 
September 19, 1986 


APPLE Computer is still working on lots of other Technical Notes. If there are any 
subjects which you would like to see treated in a Technical Note, please send a note at 
the following address: 


Macintosh Technical Notes 

c/o Apple Computer 

20525 Mariani Ave. MS 27-T 
Cupertino, CA 95014 


Apple Computer want Technical Notes to be distributed as widely as possible. The 
surest way to get them is to subscribe directly from Apple. However, Apple Computer is 
also going to distribute Technical Notes to user groups and upload them to various 
electronic builetin board systems, and it is placing no restrictions on copying them 
(except that they may not be resold). Also, registered developers will receive Technical 
Notes as part of their registration fee. | 


Macintosh Technical Notes are published at least bi-monthly. To receive 6 packages of 
Technical Notes (each package containing approximately 10 notes), send $25 
(California residents please add sales tax) to: 


Macintosh Technical Notes 
Apple Computer Mailing Facility 
467 Saratoga Avenue, Suite 621 
San Jose, CA 95129 


Remember that Apple Computer is distributing Mac Technical Notes widely and it is 
encouraging people to copy them, so you'll be able to obtain them from other sources 
as well; subscribing ensures that you'll get them directly from Apple when they're 
published. 


Apple Computer hopes that Macintosh Technical Notes will provide you with lots of 
valuable information while you’re developing Macintosh software. 


The following pages list all Technical Notes that have been released. 
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Technical Note #0 


Subject 

system Resources 

Macintosh Compatibility Guidelines 

List of Command-Shift-Number Keys 
GetNewDialog Error Return 

Modeless Dialogs/Desk Accessories 

Shortcut for Owned Resources 

A Few Quick Debugging Tips 

RecoverHandle Bug in AppleTalk Pascal Interfaces 
Will Your AppleTalk Application Support Internets? 
Pinouts 

Memory-based MacWrite Format 

Disk-based MacWrite Format 

MacWrite Clipboard Format 

The INIT 31 Mechanism 

Finder 4.1 

MacWorks XL 

New Low-Level Printer Driver Calls 

Text Edit Conversion Utility 

How to Produce Continuous Sound W/O “Clicking” 
Data Servers on Appletalk 

Internal Picture Format 

TEScroll Bug on Macintosh Plus 

Life After Font/DA Mover - Desk Accessories 
Available Volumes and Files 

Don’t Depend on Register AS Within Trap Patches 
Accuracy of Charwidth and Stringwidth 

not yet released 

Finders and Foreign Drives 

Resources Contained in The Desktop File 

FONT Height Tabies 

not yst released 

Reserved Resource Types 

ImageWriter II Paper Motion 

User items in Dialogs 

QuickDraw Picture Problem 

Drive Queue Element Format 

Differentiating Between Logic Boards 

The Macintosh Plus ROM Debugger 

segment Loader Patch 

Finder Flags 

Drawing Into an Offscreen Bitmap 

Pascal Routines Passed by Pointer 

Calling LoadSeg 

HFS Compatibility Issues 

Inside Macintosh Quick Reference 

Separate Your Resource Files During Development 
Customizing SFGetFile 

Bundies 
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49 Identical to Technical Note #44 


50 ResLoad 12/85 
51 Debugging Using PurgeMem and CompactMem 12/85 
52 Calling _Launch From a High-Level Language 12/85 
53 MoreMasters Revisited 12/85 
54 Limit to Size of Resources 12/85 
55 Drawing Icons 12/85 
56 Break/CTS Device Driver Event Structure 12/85 
57 Macintosh Plus Overview 1/86 
57a Macintosh Plus Overview(update) 3/86 
58 International Utilities Package Bugs 1/86 
59 Pictures and Clip Regions 1/86 
60 Drawing Characters in a Narrow GrafPort 1/86 
61 GetltemStyle Bug 1/86 
62 Don't Use Resource Header Application Bytes 1/86 
63 WriteResource Bug Patch 3/86 
64 IAZNotify Pointer 1/86 
65 Macintosh Plus Pinouts 3/86 
66 Determining Which File System is Active 3/86 
67 Finding the ‘Blessed Folder’ 3/86 
68 searching All Directories on an HFS Volume | 3/86 
69 setting ioFDirindex in PBGetCatInfo Calls 3/86 
70 Forcing Sony Disks to be Either 400K or 800K 3/86 
71 Finding Drivers in the Unit Table 3/86 
72 Optimizing for the LaserWriter—Techniques 3/86 
73 Color Printing 3/86 
74 Don’t Use the Resource Fork for Data 3/86 
75 The Installer and Scripts 3/86 
76 The Macintosh Plus Update Installation Script 3/86 
77 HFS Ruminations 7/86 
78 Resource Manager Tips 7/86 
79 ZoomWindow 7/86 
80 Standard File Tips 7/86 
81 Disk Caching 7/86 
82 TextEdit: Advice & Descent 7/86 
83 system Heap Size Warning , 7/86 
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Macintosh Technical Notes € 
#1: Desk Accessories and System Resources 


See Also: The Resource Manager: A Programmer's Guide 


Written by: Bryan Stearns 25-Feb-85 





This note deals with the problem of using system resources from desk 
accessories, without interfering with operation of the running application. 





When a desk accessory needs to use a system resource, such as the 'watch' cursor, it 
must get it from the system resource file. A problem arises, however, when the 
running application is also using the same resource; if the accessory releases the 
resource, the Resource Manager marks it as purgable - it may be tossed out of memory 
at the next heap compaction, leaving the application's copy of the resource handle 
pointing at a bad master pointer (which may be used later to point at something else). 


On the other hand, if the accessory leaves the resource unreleased, there will be a 
permanent handle floating in memory - not a friendly thing for an accessory to do (take 
only pictures, leave only footsteps, remember’). 


The solution to this problem lies in the mechanism that the Resource Manager uses to 
maintain purgeable resources. When a resource is purged, the resource handle is set 
to point at a master pointer of zero; this is a flag to the resource manager that the 
resource must be reloaded before being used again. Also, if a resource is requested 
while ResLoad is set FALSE, the resource will not be loaded; a handie will be 
allocated and returned, but its master pointer will be 0, as if it had been purged. 


A desk accessory can use this to determine whether or not the resource it needs was in 
memory before it was invoked, using the following fragment of code (watchHdl is a 
Handle; appWatch IS @ BOOLEAN): 


{Get the watch; set appWatch if it was already in} 
{memory, so we won't mess up the application} 
SetResLoad (FALSE) ; 


watchHdl := GetResource('CURS', watchCursor); 
appWatch := (watchHdl* <> NIL); 
SetResLoad (TRUE) ; 


watchHdl := GetResource('CURS', watchCursor); 
{use the watch} 


{throw away the watch if the app wasn't using it} 
IF NOT appWatch THEN ReleaseResource (watchHdl) ; 
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#2: Macintosh Compatibility Guidelines 


see also: Technical Note #57—Macintosh Plus Overview 
Written by: Cary Clark/Scott Knaster January 21, 1986 
Modified by: scott Knaster April 21, 1986 





Apple has many enhancements planned for the Macintosh family of computers. To help 
ensure your. software's compatibility with these enhancements, check each item in this 
note to be sure that you're following the recommendations. 


if your software is written in a high-level language like Lisa Pascal and if you adhere to 
the guidelines listed in inside Macintosh, many of the questions in this note won't 
concern you. If you develop in assembly language, you should read each question 
carefully. If you answer any question "yes", your software may encounter difficulty 
running on future Macintosh computers, and you should take the recommended action 
to change your software. 


1. Do you depend on any 68000 instructions which require that the 
processor be in supervisor mode? 


In general, your software should not inciude instructions which depend on supervisor 
mode. These include modifying the contents of the status register. Most programs 
which modify the status register are only changing the Condition Code Register (CCR) 
half of the status register, so an instruction which addresses the CCR will work fine. 
Your software should also not use the User Stack Pointer (USP) or turn interrupts on 
and off. 


2. Do you have any code which executes in response to an exception and 
relies on the position of data in the exception's local stack frame? 


Exception stack frames vary on different microprocessors in the 68000 family, some of 
which may be used in future Macintosh computers. In particular, you should avoid 
using the TRAP instruction. 

Note: You can determine which microprocessor is installed by examining the 
low-memory global called cPUF Lag (a byte at $12F). These are the values: 


CPUFIag microprocessor 
$00 68000 
$01 68010 
$02 68020 
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3. Do you modify any low-memory globals not documented in Inside 
Macintosh? 


Other microprocessors in the 68000 family use the exception vectors in locations $0- 
through $FF in different ways. Also, any location below the system heap ($100 through 
$13FF) which is not documented is not guaranteed to be available for use in future 
systems. 


4. Do you make assumptions about the file system which are not 
consistent with both the original Macintosh File System and the 
Hierarchical File System? 


Your applications should be compatible with both file systems. The easiest way to do 
this is to stick to the old files system trap calls (which work with both file systems) and 
avoid direct manipulation of data structures such as file control blocks and volume 
control blocks whenever possible. 


5. Do you allocate any objects in the system heap? 


space in the system heap is extremely limited. You should avoid using the system 
heap; if you must, only allocate very small objects (about 32 bytes or less) in the system 
heap. If you need memory which is not reinitialized when the application ends, install it 
with an INIT resource above BufPtr and move BufPtr down (see Technical Note #14 
for information about moving BufPtr). 


6. Do you depend on the system or application heaps starting at a 
hard-coded address? 


The starting addresses and size of the system and application heaps has already 
changed (Macintosh vs. Macintosh Plus) and will change again in the future. Use the 
global Appl Zone to find the application heap and SysZone to find the system heap. 
Also, don't count on the application heap zone starting at an address less than 65536 
(that is, a system heap smaller than 64K). 


7. Do you look through the system's queues directly? 


In general, you should avoid examining queue elements directly. Instead, use the 
Operating System calls to manipulate queue elements. 
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8. Do you directly address memory-mapped hardware such as the VIA, 
the SCC, or the IWM? 


Future machines may include a memory management unit (MMU) which may prevent 
access to memory-mapped hardware. Also, these memory-mapped devices may not be- 
present on future machines. You should avoid accessing this memory directly and use 
trap calls instead (disk driver, serial driver, etc.). If you must access the hardware 
directly, get the base address of the device from the appropriate low-memory global 
(obtainable from includes and interface files), since the addresses of these devices are 
likely to change: 7 


device global 
VIA $1D4 
SCCRd $1D8 
SCCWr $1DC 
IWM $1E0 


9. Do you assume the location or size of the screen? 


d 
The location and size of the screen may change in future machines. You can determine 
the location and size of the screen by examining the QuickDraw global variable 
ScreenBits. 


10. Does your software fail on the Macintosh XL or Macintosh Plus? 


if so, you should determine the reason. Failure to run on all versions of the Macintosh 
may indicate problems which will prevent your software from working on future 
machines. 


11. Do you change the master pointer flags directly with BSET or BCLR 
instructions? 


in the future, all 32 bits of a master pointer may be used, with the flags byte moved 
elsewhere. Use the Memory Manager calls HPurge, HNoPurge, HLock, HUnlock, 
HSetRBit, HClrRBit, HGetState, and HSetState to manipulate the master pointer 
flags. (See Technical Note #57 for information on these calls.) 

12. Do you check explicitly for just 128K, 512K, and 1M RAM sizes? 


You should be flexible enough to allow for non-standard memory sizes. This will allow 
your software to work in environments like the Switcher. 
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13. is your software incompatible with a third-party vendor's hardware? 


lf so, the incompatibility may prevent your software from working on future machines. 
You should research the incompatibility and try to determine a solution. 


14. Do you rely on system resources being in RAM? 


On the Macintosh Plus and future systems, some resources are in ROM. You should not 
assume, for example, that you can regain RAM space by releasing system resources. 


15. Does your software have timing-sensitive code? 


Future machines will run at different clock speeds, so timing loops will be invalid. You 
can use the trap call Delay for timing, or you can examine the global variable Ticks. 
For precise timings on the Macintosh Plus, use the Time Manager to access the VIA 
timers. 


16. Do you have code which writes to addresses within the code itself? 

A memory management unit (MMU) will likely prevent code from writing to addresses 
within code memory. Also, some microprocessors in the 68000 family cache code as 
i's encountered. Your data blocks should be allocated on the stack or in heap blocks 
separate from the code, and your code should not modify itself. 

17. Do you rely on keyboard key codes rather than ASCII codes? 

The Macintosh and Macintosh Plus keyboards are slightly different; future keyboards 
may be different from them. For textual input, you should always read ASCII codes 
rather than key codes. 


18. Do you rely on the format of packed addresses in the trap dispatch 
table? | : 


The trap dispatch table on a Macintosh Plus is not packed. There's no guarantee of the 
format in the future. You should use the system calls GetTrapAddress and 
SetTrapAddress to manipulate the trap dispatch table. 


19. Do you store information in the application parameters area (the 32 
bytes between the application and unit globals and the jump table)? 


This space is reserved for use by Apple. 
20. Do you depend on undocumented values in registers after a trap call? 
These values aren't guaranteed. The register conventions documented in /nside 


Macintosh will, of course, be supported. Often, you may not realize that your code is 
depending on these undocumented values, so check your register usage carefully. 


Technical Note #2 page 4of5 Macintosh Compatibility Guidelines 


21. Do you use the Resource Manager calls AddReference Or 
RmveReference? 


These calls have been removed from the Macintosh Plus ROM. They are no longer 
supported. : 


22. Do you use the IMMED bit in File Manager calls? 

This bit, which was documented in early versions of Inside Macintosh as a special form 
of File Manager call, actually did nothing. In the Hierarchical File System, this bit 
indicates that the call has a parameter block with hierarchical information. Your code 
should not use this bit as the IMMED bit. 

23. Do you make assumptions about the number and size of disk drives? 
There are now three sizes of Apple disks for the Macintosh (400K, 800K, and 20M), as 
well as many more from third-party vendors. You should use Standard File and File 
Manager calls to determine the number and size of disk drives. 

24. Do you depend on the alternate (page 2) sound or video buffers? 
Future machines may not support the alternate sound and video buffers. 

25.. Do you print by sending ASCII directly to the printer driver? 

To retain compatibility with both locally-connected and AppleTalk-connected printers, 
you should print using either the Printing Manager or the text-streaming and 
bitmap-printing control calls to the printer driver, as documented in Inside Macintosh. 


26. Does your application fail when it's the startup application (i.e., 
without the Finder being run first)? 


If so, you're probably not initializing a variable. If your application does not work as the 


startup application, you should determine why and fix the problem, since it may cause 
your application to fail in the future. 
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#3: List of Command-Shift-Number Keys 


See also: Macintosh Owner's Manual 
The Toolbox Event Manager Programmer's Guide 
Technical Note #2 -- Using EjectNotify 


Written by: Harvey Alcabes March 3, 1985 
Modified by: Ginger Jernigan April 25,1985 


List of Command-Shift-Number key sequences and how to install your own. 


In the standard system, there are five Command-Shift-number key combinations 
defined that are automatically captured and processed by GetNextEvent. These 
Command-Shift-number key combinations are: 


Command-Shift-1 Eject internal disk 

Command-Shift-2 Eject external disk 

Commanca-Shift-3 Save current screen as MacPaint file named 
Screen 0, Screen 1, ... Screen 9 

Command-Shift-4 Print the active window . 


Command-Shift-Caps Lock-4 Print the entire screen 


Numbers 1 and 2 are automatically processed by GetNextEvent. Numbers from 3 to 9 
are also captured by GetNextEvent, but are processed by calling FKEY resources. You 
can implement your own actions for Command-Shift-number combinations for numbers 
3 to 9 by defining your own FKEY resource. The routine must have no parameters. The 
ID of the resource must correspond to the number you want the routine to respond to. 
For example, if you want to define an action for Command-Shift-8, you would define an 
FKEY resource with an ID of 8. 


Notes: 

You should not change the function of numbers 3 and 4. These have been universally 
defined to have the functions described above. Changing them would only confuse 
users of your product. 


The Command-Shift-4 and Command-Shift-Caps Lock-4 combinations will currently 
only print to an Imagewriter (8' or 15") connected to the printer port. To print to 
another printer, use Command-Shift-3 and print using MacPaint. 


The standard Macintosh XL screen is too wide to print nicely on an 8" or 15° 
Imagewriter. The picture wraps around. 
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#4: Error Returns from GetNewDialog 
See also: The Dialog Manager 


Written by: Russ Daniels 4 April 85 


When calling GetNewDialog to retrieve a dialog template from a previously 
opened resource file, how are error conditions indicated to the caller? 


Unfortunately, they aren't. The Dialog Manager calls GetResource and 
blindly assumes the returned value is good. Since it doesn't check, you have 
two choices. The first is to call GetResource on the Dialog Template, Item 
List, and resources needed by items in the Item List yourself. The second 
is to assure the dialog template will be available when you build your 
product. This is really an adequate solution: If somebody uses the 
Resource Editor to remove your dialog template, you can hardly be blamed 
for not executing properly. 


A good debugging technique to catch this sort of problem is to put an odd 
value at absolute memory location 3 (the least significant byte of the first 
long word of memory). If you do that, when the Dialog Manager tries to 
dereference the Nil handle returned by the Resource Manager, you'll get an 
address error with some register containing the odd value. If you list the 
instructions around the program counter, you'll often see something like: 


Move.| (A2),A1 ; in effect (0),A1 
Move.! (A1),A1 ; the error occurs here 


Thankfully, GetNewWindow and most of the other GetSomething calls will 
return Nil if the template is not found. 
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#5: Using Modeless Dialogs from Desk Accessories 


See also: The Dialog Manager 
The Desk Manager 


Written by: Russ Daniels 4 April 85 


a e ere 


When a desk accessory creates a window (including a dialog window) it 
must set the windowkind to its refnum--a negative number. When the 
application calls GetNextEvent, the Event Manager calls SystemEvent, 
which checks to see if the event belongs to a desk accessory. SystemEvent 
checks the windowkind of the frontmost window, and uses the (negative) 
number for the refnum to make a control call, giving the desk accessory a 
shot at the event. Then SystemEvent returns True, and GetNextEvent 
returns False. 


So, your desk accessory gets an event from SystemEvent. Since your 
window is a modeless dialog, you call IsDialogEvent, which mysteriously 
returns False. What is going on? 


Like SystemEvent, IsDialogEvent also checks the windowkind of windows in 
the windowlist, looking for dialog windows, which have a windowkind of 2. 
In this case, it finds none, and does nothing. 


The solution is to change the windowkind of your window to 2 before 
calling the Dialog Manager. That way, it can handle the event properly. 
Before returning to SystemEvent, be sure to restore the windowkind. That 
way, when the application calls the Dialog Manager with the same event 
(the application should pass all events to Dialog Manager if it has any 
Modeless Dialogs itself), the Dialog Manager will ignore it. 
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#6: Shortcut for Owned Resources 
See also: The Resource Manager 


Written by: Bryan Stearns May 10, 1986 





To allow the Font / Desk Accessory Mover to renumber accessories as needed when 
moving them between system files, desk accessories should use the “owned resource" 
protocol described on page l-109 of inside Macintosh: the Resource Manager. 


The "UNamAcc" example desk accessory, included in the May '85 Software 
Supplement, uses this protocol. In the source for the accessory, all resource IDs are 
zero-based. At runtime, a routine is called once to find the current "base" value to add 
to a resource's zero-based value to get the actual current ID of that resource. Then, 
when a resource is needed, its zero-based value is added to the resource base value, 
giving the actual resource ID to be used in future Resource Manager calls. 


Note that though the "UNamAcc" source has zero-based resource IDs, the Resource 
Compiler input file (‘UNamAccR") has the resources (and the accessory code itself) 
numbered as if the accessory were DRVR ID #24; this is so that all the resources get 
moved together when the accessory is first fed to the Font / Desk Accessory Mover. 


Here's the source to GetResBase, from "UNamAcc.Asm": 


;Function GetResBase (ourResBase: Integer) :Integer; 
; GetResBase takes the driver number and returns the ID 
; of the first resource owned by that driver. This is 
; according to the private resource numbering convention 
; documented in the Resource Manager. 

.Def GetResBase 
GetResBase 


MOVE.L (SP) +,A0 Get return address 


f 
MOVE.W (SP)+,DO ; Get driver number 
NOT.W DỌ ; Change to unit number 
ASL.W #5,D0 ; Move it over in the word 
ORI. W #$c000,DO ; Add the magic bits 
MOVE.W DO, (SP) ; Return function result 
JMP (A0) ; and return 
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#7: A Few Quick Debugging Tips 


Written by: Jim Friedlander April 16, 1986 


This Technical Note presents a few quick debugging tips which should help 
make your debugging easier. 


etting memory location 0 to somethin 

Dereferencing NIL handles can cause real problems for an application. If location O 
(NIL) is something even, the dereference will not cause an address error, and the 
application can run on for quite a while, making tracing back to the problem quite 
difficult. If location 0 is something odd, such as $01010101, an address error will be 
generated immediately when a nil handle is dereferenced. An address error wili also 
be generated, of course, when the ROM tries to dereference a NIL handle, such as 
when you call HNoPurge (hnd1l) , where hnd1 is NIL. 


Some user areas of the TMON debugger set location 0 to ‘NIL! or $46494c21. if you 
are using MacsBug, you should include code in your program that sets location 0 to 
something odd. The Finder used to set location 0 to the even value $464F424A, or 
'FOBJ'. On newer systems, Launch Sets location 0 to $00f80000. Of course, there is 
no need to ship your application with this code in it—it's just for debugging purposes. 


Checksumming for slow motion mode 
Entering the MacsBug command "SS 400000 400000" will cause MacsBug to 


checksum the location 400000 every time an instruction is executed. Checksum the 
ROM, because it will not change while your program is executing (the ROM may change 
in between launches of your application, but that's OK)! This will cause the Mac to go 
into slow motion mode. For example, you will need to hold down the mouse button for 
about 10 seconds to get a menu to pull down—you can see how the ROM draws menus, 
grays text, etc. 7 


This technique is very handy for catching problems like multiple updates of your 
windows, redrawing scroll bars more than once, that troublesome flashing Growlcon, 
etc. To turn slow motion mode off, simply enter MacsBug and type "SS". 


TMON can also perform this function, but in a much more flexible way. TMON is much 
faster when it calculates the checksum, since it only calculates checksums after each 
trap, so you can checksum different amounts of the ROM depending on how much you 
want things to slow down. 
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Checksumming on MemeErr 


A iot of programs don't check MemError as often as they should. If you are having 
strange, memory related problems, one thing that you can do to help find them is to 
checksum on MemErr (low memory global word at $220). In MacsBug, type "SS 220- 
221". In TMON, enter 220 and 221 as limits on the ‘Checksum (bgn end): ' line and on 
the line above, enter the range of traps you wish to have the checksum calculated after. 
When MemErr changes, the debugger will appear, and you can check your code to 
make sure that you are checking MemErr. If not, you might have found a problem that 
could cause your program to crash! 


hecksummin n mast int 


Due to fear of moving memory, some programmers lock every handle that they create. 
Of course, handles need only be locked if they are going to be dereferenced and if a 
call will be made that can cause relocation. If you suspect that a particular memory 
block is moving on you when you have its handle dereferenced, you can checksum the 
master pointer (the handle you got back from NewHand1e is the address of the master 
pointer). Your program will drop into the debugger each time your handie 
changes—that is, either when the block it refers to is relocated, or when the master 
pointer's flags byte changes. 
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#8: RecoverHandle Bug in AppleTalk Pascal Interfaces 
See also: AppleTalk Manager 
Written by: Bryan Stearns April 21, 1986 





A bug in the current AppleTalk Pascal Interfaces can cause system crashes 
if the current heap is not the application heap. Here's a description of the 
bug, and suggestions as to how you can avoid it. 





The AppleTalk Pascal Interfaces keep a handie for each pending AppleTalk call. These 
handles are locked and unlocked as needed, and disposed of when the call compietes. 


Each time a call is made through the Pascal Interfaces, each handle is checked to see if 
it's time to throw it away. This avoids calling DisposHandle from an interrupt routine. 


The problem is the following: the Pascal Interfaces use RecoverHandle at interrupt 
time. Unfortunately, RecoverHandle uses the current heap zone pointer to determine 
the handle being recovered. If the current heap zone is not the zone which owns the 
handle involved, random crashes can occur. 


You can reduce the chance that this problem will occur, by never changing the current 
zone (that is, don't call Set Zone). However, this is not a complete cure for this problem; 
although an application can avoid changing heaps while AppleTalk calls (made 
through the Pascal Interfaces) are pending, there's nothing to stop a desk accessory 
from changing the current zone without the application's knowledge (of course, the 
accessory would change it back before returning to the application, but there's still that 
window of uncertainty). 


The only complete cure for this problem is to make all calls to AppleTalk using Device 
Manager Control calls, as described in the AppleTalk Manager chapter of /nside 
Macintosh, in the section "Using AppleTalk from Assembly Language". 


We're looking into revising the Pascal Interfaces to fix this problem. When a fixed 
version becomes available, it will be shipped as part of a Software Supplement. 
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#9: Will Your AppleTalk Application Support Internets? 


See also: The AppleTalk Manager 
Inside AppleTalk 
Written by: Bryan Stearns April 2, 1986 





Soon AppleTalk networks will be connected together as Internets. It's 
important that your application work across internets; this note contains 
information on the differences between life on a single AppleTalk, and life 
on an internet. 





You read about them in Inside AppleTalk; soon they'll be here. What do you need to do 
about it? 


ion j r 
Several bugs relating to internet operation have been found and fixed since the 
AppleTalk versions which had pairs of version numbers (like ATP 3.1A / MPP 3.1B, 
etc.). Version 39 was the first version with the fixes; a trivial change was made to the 
drivers, giving Version 40, the current version. It's downloadable from CompuServe 
(but don't forget to contact our Software Licensing department at (408) 973-4667 for 
licensing information, before shipping your software!). 


Use a high-level network protocol 
Make sure you use the Datagram Delivery Protocol (DDP), or a higher AppleTalk 


protocol based on DDP, like the AppleTalk Transaction Protocol. Be warned that 
Link-Access Protocol packets will not make it across bridges to other AppleTalk 
networks! Also, don't broadcast; broadcast packets will not be forwarded by bridges 
(broadcasting using protocols above LAP is discouraged, anyway). 


Use Name-Binding 

As usual, use the Name-Binding Protocol to announce your presence on the network, 
as well as to find other entities on the network. Pay special attention to zone name 
fields: the asterisk (as in "“MyLaser:LaserWriter:*") in a name you LookUp is now 
important; it means "my zone only" (a method will be provided for finding out what other 
zones exist). The zone field should always be an asterisk when registering a name. 


p Attention to Network Number Fiel 
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When handling the network addresses returned by NBPLookUp (or anyone else), don't 
be surprised if the network number field is non-zero (see below for notes on handling 
of retries in transactions with non-local nodes). 


Reconsider the val 've chosen for retry and timeout 

There are no set rules for choosing values for retry and timeout (under ATP). There are 
several factors involved. How long will it take this command to execute before the 
response will be sent? How reliable is the device? Does it have interrupts disabled for 
periods of time in which packets might get lost? What kind of performance does the 
user of my application expect? 


in general, 10 to 15 seconds is a reasonable timeout value for a command that can be 
executed immediately (i.e., the responding machine doesn't have to do any 
processing, and can turn around a response with no delay). This covers a reasonably 
busy internet where no more than a few "hops" (across bridges) might be involved. A 
network mail application, or one where many half-bridges might be in use, should 
allow longer timeouts. Of course, most transactions will complete in much less than the 
allotted time, but longer than 10 or 15 seconds may be too long for a user to wait (You 
can also consider handling retries yourself, especiaily in the case of NBP LookUp calls). 


The ultimate approach would be to dynamically tailor your timeouts, based on current 
network throughput. When you first contact another network entity, send a test packet 
and see how long it takes for the other entity to respond (by managing your own 
NBP LookUp retries, you could even do this as part of your lookup). Base your timeout 
and retry values on this delay, and dynamically adjust it based on changes in 
transaction completion speed. 


If a transaction fails, try using NBPConfirm to reestablish contact with the other node; if 
this succeeds, retry the transaction. 


Am I running_on an internet? 
The low memory global ABridge is used to keep track of a bridge on the local 


AppleTalk network (NBP and DDP use this value). If ABridge is non-zero, then you're 
running on an internet; if it's zero, chances are, you're not (this is not guaranteed, 
however, due to the fact that the ABridge value is "aged", and if NBP hasn't heard from 
the bridge in a long time, the value is cleared). 


Watch out for out-of-sequence requests. and non-exactly-once requests 


Due to a "race" condition on an internet, it's possible for an exactly-once ATP packet to 
slip through twice; to keep this from happening, send a sequence number as part of the 
data with each ATP packet; whenever you make a request, bump the sequence 
number, and never honor an old sequence number. 
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#10: Pinouts 

See also: Macintosh Hardware Manual 

Written by: Mark Baumwell April 26, 1985 
Modified: July 23, 1985 





This note gives pinout descriptions for the Macintosh ports, Macintosh cables, 
and various other products. 





Below are pinout descriptions for the Macintosh ports, cables, and various other products. 
Please refer to the Macintosh Hardware chapter for more information, especially about 
power limits (the Macintosh Hardware chapter is included in the May Software 
Supplement). Note that any unconnected pins are omitted. i 


Macintosh Port Pinouts 


Macintosh Serial Connectors (DB-9) 


Pin D ‘otion/N 
1 Ground 

2 +5V See Macintosh Hardware chapter for power limits 

3 Ground 

4 TxD+ Transmit Data line 

5 TxD- Transmit Data line 

6 +12V See Macintosh Hardware chapter for power limits 

7 HSK HandShake: CTS or TRxC, depends on Zilog 8530 mode 
8 RxD+ Receive Data line; ground this line to emulate RS232 

9 RxD- Receive Data line 
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Macintosh Mouse Connector (DB-9) 


Pin Name Rescription/Notes 

1 Ground 

2 +5V see Macintosh Hardware chapter for power limits 

3 GND Ground 

4 X2 Horizontal movement line (connected to VIA PB4 line) 

5 X1 Horizontal movement line (connected to SCC DCDA- line) 
7 SW- Mouse button line (connected to VIA PB3) 

8 Y2 Vertical movement line (connected to VIA PBS line) 

9 


Y1 Vertical movement line (connected to SCC DCDB- line) 


Macintosh Keyboard Connector (RJ-11 Telephone-style jack) 


Pin Name Description/Notes 

1 Ground 

2 KBD1 Keyboard clock 

3 KBD2 Keyboard data 

4 +5V see Macintosh Hardware chapter for power limits 


Macintosh External Drive Connector (DB-19) 


Pin Name Description/Notes 

1 Ground 

2 Ground 

3 Ground 

4 Ground 

5 -12V See Macintosh Hardware chapter for power limits 
6 +5V See Macintosh Hardware chapter for power limits 
T +12V See Macintosh Hardware chapter for power limits 
8 +12V See Macintosh Hardware chapter for power limits 
10 PWM. Regulates speed of the drive 

11 PHO Control line to send commands to the drive 

12 PH1 Control line to send commands to the drive 

13 PH2 Control line to send commands to the drive 

14 PH3 Control line to send commands to the drive 

15 WrReqa- Turns on the ability to write data to the drive 

16 HdSel Control line to send commands to the drive 

a7 Enbl2- Enables the Rd line (else Rd is tri-stated) 

18 Rd Data actually read from ihe drive 

19 Wr Data actually written to the drive 
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Other Pinouts 


Macintosh XL Serial Connector A (DB-25) 


Pin 

1 Ground 
2 TxD 

3 RxD 

4 RTS 

5 CTS 

6 DSR 

7 Ground 
8 DCD 
15 TxC 

17 RxC 

24 TEXT 


Descrintior/N 


Transmit Data line 
Receive Data line 
Request to Send 
Clear To Send 
Data Set Ready 


Data Carrier Detect 

Connected to TRxCA 
Connected to RTxCA 
Connected to TRxCA 


Macintosh XL Serial Connector B (DB-25) 


Ground 
TxD- 

RxD- 
HSK/DSR 
Ground 
RxD+ 
TXD+/DTR 


SoVFeCN eR 


O wo 


Description/Notes 


Transmit Data line 
Receive Data line 
TRxCB or CTSB 


Receive Data line 
connected to DTRB 


Apple 300/1200 Modem Serial Connector (DB-9) 


Name 
DSR 
Ground 
RxD 
DTR 
DCD 
Ground 
TxD 


a: 
3 


Description/Notes 
Output from modem 
Output from modem 
Input to modem 
Output from modem 


Input to modem 


Apple Imagewriter Serial Connector (DB-25) 


ImageWriter Name 
Ground 
SD 

RD 
RTS 
Ground 
FAULT- 
DTR 


mwas bh GN — 


oO > 
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Descriotion/N 


Send Data; Output from imagewriter 
Receive Data; Input to Imagewriter 
Output from Imagewriter 


False when deselected; Output from [magewriter 
Output from Imagewriter 
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Apple LaserWriter AppleTalk Connector (DB-9) 


1 Ground 

3 -Ground 

4 TxD+ Transmit Data line 

5 TxD- Transmit Data line 

7 RXCLK TRxC of Zilog 8530 
8 RxD+ Receive Data line 

9 RxD- Receive Data line 


Apple LaserWriter Serial Connector (DB-25) 


LaserWriter Name Description/Notes 

1 Ground 

2 TXD- Transmit Data; Output from LaserWriter 

3 RXD- Receive Data; Input to LaserWriter 

4 RTS- Output from LaserWriter 

5 CTS Input to LaserWriter 

6 DSR Input to LaserWriter (connected to DCBB- of 8530) 
7 Ground 

8 DCD Input to LaserWriter (connected to DCBA- of 8530) 
20 DTR- Output from LaserWriter 

22 RING input to LaserWriter 
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Macintosh Cable Pinouts 


Note for the cable descriptions below: 

1. The arrows ("--->") show which side is an input and which is an output. For example, 
the notation “a ---> b" means that signal "a" is an output and "b" is an input. 

2. When pins are said to be connected on a side in the Notes column, it means the pins 
are connected on that side of the connector. 


Macintosh Imagewriter Cable 
(part number 590-0169) 


Macintosh Name imagewriter Notes 

(DBS) (DB25) 

1 Ground 1 

3 Ground 7 pins 3, 8 connected on Macintosh side 
5 TxD- —> RD 3 RD = Receive Data 

T HSK <— DTR 20 

8 RxD+ = GND Not connected on Imagewriter side 

9 RxD- <— SD 2 SD = Send Data 


Macintosh Modem Cable (Warning! Don't use this cable to connect 2 Macintoshes!) 
(part number 590-0197-A) 


Macintosh Name Modem Notes 

(DB9) (DB9) 

3 Ground 3 pins 3, 8 connected on EACH side 
5; TxD- ---> TxD 9 

6 +12V —> DTR & 

7 HSK <~- DCD 7 

8 No wire 8 

9 RxD- <-— RxD 5 


Macintosh to Macintosh Cable (Macintosh Modem Cable with pin 6 clipped on both ends.) 


Macintosh Name Macintosh Notes 

(DB9) (DB9) 

3 Ground 3 pins 3, 8 connected on EACH side 
5 TxD- ——> RxD- 9 

ri HSK <— DCD 7 

8 No wire 8 

9 RxD- <— TxD- 5 
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Macintosh External Drive Cable 
(part number 590-01 83-B) 


Macintosh Name ny Driv 
(DB9) (20 Pin Ribbon) 
1 Ground 1 

2 Ground 3 

3 Ground 5 

4 Ground 7 

6 +5V 11 

7 +12V 13 

8 +12V 15 

10 PWM 20 

11 PHO 2 

12 PH1 4 

13 PH2 6 

14 PH3 8 

15 WrRea- 10 

16 HdSel 12 

17 Enbi2- 14 

18 Rd 16 

19 Wr 18 


Macintosh XL Null Modem Cable 
(part number 590-0166-A) 


Macin Name OTE Notes 

(DB25) (OB25) 

1 Ground 1 

2 TxD- —> RxD 3 

3 RxD- <— TxD 2 

4,5 RTS,CTS --> DCD 8 pins 4,5 connected together 
6 DSR <— DTR 20 

7 Ground 7 

8 DOD x RTS,CTS 4,5 pins 4,5 connected together 
20 DTR ---> DSR 6 
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Macintosh to Non-Apple product Cable Pinouts 


Macintosh to IBM PC Serial Cable #1 (not tested) 


Macintosh Name IBM PC Notes 
(DB9) (DB25) 
3 Ground 7 pins 3, 8 connected on Macintosh side 
5 TxD- —> RxD 3 
7 HSK <-- DTR 20 
8 RxD+ 5 Ground Not connected on IBM side 
9 RxD- <-- TxD 2 
CTS <— RTS 4-5 pins 4,5 connected on IBM side 
DSR <—- DCD,DTR 6-8-20 pins 6,8,20 connected on IBM side 


Macintosh to IBM PC Serial Cable #2 (not tested) 


Macintosh Name IBM PC Notes 
{DB9) (DB25) 
1 Ground 1 
3 Ground 7 pins 3, 8 connected on Macintosh side 
5 TxD- —> RxD 3 
9 RxD- <— TxD 2 
CTS <- RTS 4-5 pins 4, 5 connected on IBM side 
DSR <— DTR 6-8 pins 6, 8 connected on IBM side 
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#11: Memory Based MacWrite File Format 


See also: MacWrite Owner's Manual 
Technical Note #12--Disk Based MacWrite File Format 
Technical Note #13--MacWrite Clipboard Format 


Written by: Encore Systems 28-November-84 
Modified by: Encore Systems 25-April-85 
Harvey Alcabes 30-April-85 


This note describes the format of files created by MacWrite versions 2.0 and 
2.2 (also known as memory based MacWrite). 


MacWrrite creates files with a creator ID of MACA and a file type of TEXT or WORD. 
TEXT documents are created when the user saves specifying text-only and simply 
contain text in their data fork. The following is a description of WORD documents 
(MacWrite format; not to be confused with MicroSoft ™ WORD). 


A MacWrite file begins with global data concerning the state of the program when the 
file is saved. After that, the information about each window Is listed, with the actual 
paragraph data for each window following. The three different types of windows are the 
main document, header, and footer. 


Global Variables 


Bytes Item 

0-1 Version Number - The version number of the file format. 

2-3 Paragraph Offset - The position of the start of paragraph data in the 
file. 

4-5 Main Document Paragraph Count - Number of paragraphs in the 


main document. (At least one forthe ruler and one for the cursor.) 
6-7 Header Paragraph Count - Number of paragraphs in the header. 
(At least one for the ruler and one for the cursor.) 
8-9 Footer Paragraph Count - Number of paragraphs in the footer. (At 


least one for the ruler and one for the cursor.) 
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10 


11-12 
13 
14 
15 
16-17 


18-19 


Title Page Flag - Boolean : TRUE if the first page headers and 
footers are not to be drawn. 

Unused. 

Footer Displayed Flag - Boolean : TRUE if the footer is displayed. 
Header Displayed Flag - Boolean : TRUE if the header is displayed. 
Rulers Hidden Flag - Boolean : TRUE if rulers are hidden. 

Active Document number - Teils which window was activated at the 
time of the save (O=main, 1=header, 2=footer). if itis -1, then all 
paragraph heights and line height arrays need to be recalculated. 


Starting Page Number - The page number of the first page. 


Printing Variables - This is the 120 byte universal printing record. 


Window Variables - The main document variables are stored first, followed by the 
header and then the footer. 


Bytes 
0-3 


4-7 


10-11 


12-15 
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ean of Selection - Paragraph number in the high word (bytes 2 and 
3) and inclusive character position in the low word (bytes 0 and 1). 
End of Selection - Paragraph number and exclusive character 
position. (Set up the same as above.) 

Vertical Offset - The negative difference between the top of thepage 
and the top of the screen in pixels. (It is zero if the top of the page is 
at the top of the screen.) 

Need To Redraw - Teils the first paragraph to redraw the document 
from when loaded. 

Page Number Position - The top left point of the page number icon, 


with the origin being the top left corner of the ruler. it is unused in 


the main document. 
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16-19 


20-23 


24-27 
28 
29 


30-31 


32-33 


Info Arrays - 


Arr lement: 
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Date Position - The top left point of the date icon, with the origin 
being the top left corner of the ruler. it is unused in the main 
document. 

Time Position - The top left point of the time icon, with the origin 
being the top left corner of the ruler. It is unused in the main 
document. 

Unused. 

Icon Redraw - Boolean : TRUE if the icons have to be redrawn. 
Icon Flag - Boolean : TRUE if the rulers were showing when the 
icons were last updated. 

Active Font Number - The font that was active at the time of the 
save. 


Active Style Number - The face that was active at the time of the 
save. 


One array for each document, and one array element for each 
paragraph. 


ttem 
Height of this paragraph in pixels. (From the top of the first line to 
the bottom of the last line in the paragraph.) 

Position of this paragraph from the top of the page in pixels. 
Page number. 

Unused 
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Paragraph Data - The main document paragraphs are stored first, then those of the 
header and footer. Each paragraph starts with a word for the type (O=ruler, 1=text par, 
eal then a word for the length of the data, followed by the actual data for the 
paragrapn. 


Text Paragraph: 

Bytes ltem 

0-1 Text length in bytes (n). 

2-(n+2) The actual ASCII data. Ends on a even word boundary. 


On an even word boundary following the text, is a word for the length of the format run in 
bytes. A format run is an array of formats. 


Formats: 
Bytes {tem 
0-1 The position of the first character that the format change applies to. 
2 Point size. 
3 otyle setting, cleared for plain, otherwise the set bits stand for: 
Bits Style 
Bit 0 Bold 
Bit 1 Italic 
Bit 2 Underline 
Bit 3 Outline 
Bit 4 Shadow 
Bit 5 Superscript 
Bit 6 Subscript 
4-5 Font number. 
6-7 Number of lines in the paragraph. (n) 
8-(n+8) Height in pixels of the each line in order. Ends on a even word 
boundary. 
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Ruler Paragraph (or Ruler Record): 


Bytes Item 

0-1 Left margin in honzontal coordinates. (Number of pixels between 
the left side of the screen and the left margin.) 

2-3 Right margin in horizontal coordinates. (Number of pixels between 
the right side of the screen and the right margin.) 

4 Justification - Can have four values: O=left, 1=center, 2=right, and 
3=fill. 

5 Number of tabs present from zero to ten. 

6-7 Spacing - To get the spacing from this integer, spacing = 1 + (n / 2). 

8-9 The indentation of the first line as a horizontal coordinate. (Number 


of pixeis between the left side of the screen and the first line 
indentation.) 

10-29 The tab array. It contains ten integer values which are the 
horizontal coordinates for the tabs. (Number of pixels between the 
left side of the screen and the tab.) Decimal tabs are negative. 

30-33 Unused. 


Picture Paragraph: A picture paragraph starts out with a rectangle containing the 
picture size, followed by a standard Quickdraw picture. 
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Summary: Your document's variables will be stored in the following order: 


Global variables 

Printing variables 

Main document's window variables 
Header's window variables 
Footer's window variables 

Main doucment's info array 
Header's info array 

Footer's info array 

Main document's paragraph data 
Header's paragraph data 
Footer's paragraph data 
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#12: Disk Based MacWrite Format 


See also: MacWrite Owner's Manual 
Technical Note #11--Memory Based MacWrite File Format 
Technical Note #13--MacWrite Clipboard Format 


Written by: | Encore Systems November 28, 1984 

Modified by: Encore Systems March 15, 1985 
Encore Systems April 25, 1985 
Encore Systems February 20, 1986 


This note describes the format of files created by MacWrite version 4.5 (also 
known as disk based MacWrite). 


é 


MacWrite creates files with a creator ID of MACA and a file type of TEXT or WORD. 
TEXT documents are created when the user saves specifying text-only and simply 
contain text in their data fork. The following is a description of WORD documents 
(MacWrite format). 


This is the file format for MacWrite 4.5, the released version of disk based MacWrrite. 
This version is available as a free upgrade to MacWrite owners through dealers and in 
the Software Supplement beginning in May 1985. Files created by pre-release 
versions of disk based MacWrite (3.0 or later but less than 4.5) may vary slightly from 
this description. 


The following variables concern the state of the program when the file is saved. The 
global, printing and document variables are stored contiguously at the beginning of the 
file and contain all the information necessary to find any of the other relevant data. All 
numbers are in decimal, unless otherwise stated. 


Global Variables 
(Please Note: For the purposes of this document the Boolean TRUE = $FF 
and the Boolean FALSE = $00) 


Bytes item 

0-1 Version number of the MacWrite that created this file( 6 means MacWrite 
4.5, 3 means MacWrite 2.2). 

2-3 The number of paragraphs in the main document. (At least one for the ruler 


and one for the cursor.) 
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10 
11 
12 
13 
14-15 


16-17 
18-21 
22-23 


24-25 


26-39 


The number of paragraphs in the header. (At least one for the ruler 
and one for the cursor.) 

The number of paragraphs in the footer. (At least one for the ruler and 
one for the cursor.) 


‘Title Page - Boolean : FALSE if the first page headers and footers are 


to be drawn. 

Unused. 

Scrap Displayed Flag - Boolean : TRUE if the scrap is displayed. 
Footer Displayed Flag - Boolean : TRUE if the footer is displayed. 
Header Displayed Flag - Boolean : TRUE if the header is displayed. 
Ruler's Displayed Flag - Boolean : FALSE if the rulers are displayed. 


Active Document - The document that is active at the time of the save. 
0 = Main Document 
1 = Header 
2 = Footer 
-1($F FFF) = whole document needs to be redrawn 


Start Page Number - The offset for the page numbers. 

Free List Array Position - Pointer to the free list of unused space. 

Free List Length - The actual length of the free list, which wili be the 
same or less than was allocated. 

Free List Allocated - The number of bytes that are allocated for the free 
list on disk. 

Unused. 


Printing Variables - This is the 120 byte universal printing record. (It goes from byte 


40 to byte 159.) 


Window Variables - These are the window variables for the footer, header, and 
main document, in that order. The footer starts at byte 160, the header at byte 206, and 
the main at 252. 


Bytes 
0-3 


4-7 


Item 

Start of Selection - Paragraph number in the high word (bytes 0-1) 
and inclusive character position in the low word (bytes 2-3). 

End of Selection - Paragraph number and exclusive character 
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10-11 


12-15 


16-17 


18-21 


22-23 


24-27 


28-31 


32-35 


36-39 
40 
4i 


42-43 
44-45 
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position. (Set up the same as above). 

Vertical Offset - The negative difference between the top of the page 
and the top of the screen in pixels. (Itis zero if the top of the page is at — 
the top of the screen.) 

Need To Redraw - Telis the first paragraph to redraw the document 
from, when loaded. 

Information Array Position - The pointer to this document's information 
array. 

Information Array Length - The length of this document's information 
array in bytes. 

Line Height Array Position - The pointer to this document's line height 
array. 

Line Height Array Length - The length of this document's line height 
array in bytes. Note: If you are trying to create a MacWrite file, this 
array cannot be empty. 

Position of Page Number - The top left point of the page number icon, 
with the origin being the top left corner of the ruler. It is unused in the 
main document. 

Position of Date - The top left point of the date icon, with the origin 
being the top left corner of the ruler. It is unused in the main 
document. 

Position of Time - The top left point of the time icon, with the ongin 
being the top left corner of the ruler. It is unused in the main 
document. 

Unused. 

Oval Redraw - Boolean : Tells whether or not to redraw ovals. 

Last Oval Update - Boolean : Tells whether ruler heights are included 
in oval positions. 

Active Style Number - The face that was active at the time of the save. 
Active Font Number - The font that was active at the time of the save. 
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Line Height Array - There is a line height array for the footer, header, and main 


Bytes 
0-1 
o-n 


document. For each paragraph there is one element in the array 
which consists of: 


tem 
Number of bytes of line height data for this paragraph (n). 
Line height information. The format of the information is as follows: 


One byte for the height of a line (in pixels), followed by an optional byte 
repeat factor equal to the number of lines (including the first line) with the 
same height. The repeat factor is distinguished from a line height by 
having its high bit set, thus limiting any line's height to a maximum of 127 
pixels, and any repeat factor to 127. 


The line height information for the next paragraph always starts on a word 
boundary. 


information Array - There is an information array for the footer, header, and main 
document. For each paragraph there is one element in the array which consists of: 


Bytes 
0-1 


2-3 
4-7 


tem 

Paragraph Height - Height of the paragraph in pixels. A positive 
value indicates text, a negative value means a picture, and zero 
is used if the paragraph is a ruler. 

Position of this paragraph from the top of the page in pixels. 
Paragraph Handle - This is the handle to the paragraph. The high 
byte (byte 4) is used to store the page number the paragraph 
begins on. Note: the low three bytes are just used in memory. 
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12-13 


14-15 


Paragraph Status Byte 


Bit ltem 

0-1 Justification Code - 
00 - Left justified. 
01 - Center justified. 
10 - Right justified. 
11 - Fully justified. 

2 In Use Bit - Set if this paragraph is in use. Do not flush a 
paragraph in this condition. Note: this is not a valid field on 
the disk, it is just used in memory. 

3 Compress Bit - Set if the paragraph was compressed 
when it was written out to disk. 

4 On Its Way Bit - Set if a disk operation has been started 
but not completed. Note: this is not a valid field on 
the disk, it is just used in memory. 

5 in Memory Bit - Set if the paragraph has been read into 
memory. Note: this is not a valid field on 
the disk, it is just used in memory. 

6 Justification Bit - 

Clear - Use the ruler justification. 
Set - Use the justification code above. 

7 Dirty Bit - Set if the paragraph changed since the last 
write to disk. Note: this is not a valid field on 
the disk, it is just used in memory. 


Paragraph Data Position - Bits C-24 contain the file 

index of the paragraph data relative to the start of the 

file. The high byte is the status byte. 

Paragraph Data Length - The length of all the paragraph 

data in bytes, including the text, format runs, etc. 

Paragraph Formats - Common format information of the paragraph for 
menu checking. 


Bit tem 

0-7 Bitmap of styles (all bits 0 means no common style) 
Bits { 
Bit 0 Plain 
Bit 1 Bold 
Bit 2 Italic 
Bit 3 Underline 
Bit 4 Outline 
Bit 5 Shadow 
Bit 6 Superscript 
Bit 7 oubscript 
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8-10 Index to size 


Value Size 
0 no common size 
1 9 
2 10 
3 12 
4 14 
5 18 
6 24 
11-15 Index into font table (ail bits 0 means no common 
font) 


Free List Array - Each element in the array consists of the following: 


Bytes Item 
0-3 Position - Corresponds to the file position of this free block. 
4-7 Free Bytes - The size of this block in bytes. 


Paragraph Data -Paragraphs are not stored in sequential order, but rather are pointed. 
to by the Paragraph Data Position and the Paragraph Data Length. 
Text Paragraph: 
Bytes item 
0-1 Text length in bytes (n). if text is compressed, (n) refers to the number of 
uncompressed characters. 
2-(N+2) Decompressed or Compressed Text : 
Decompressed - ASCII data. 
Compressed - See Compression Scheme on page 7. Ends 
on an even word boundary. 


On an even word boundary following the text is a word for the byte length of the format run. 
A format run is an array of formats. 


Formats: 

Bytes Item 

0-1 The position of the first character to which the format change applies. 
2 Point size. 
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3 Style setting, cleared for plain, otherwise the set bits stand for: 
Bits Style 
Bit O Bold 
Bit 1 Italic 
Bit 2 Underline 
Bit 3 Outline 
Bit 4 Shadow 
Bit 5 Superscript 
Bit 6 Subscript 

4-5 Font number. 

Ruler Paragraph: 

Bytes tem 

0-1 Left margin in horizontal coordinates. (Units of 1/80" measured from the left 
edge of the ruler. The ruler starts at 1", so a value of O means a i"margin or first 
line indent) 

2-3 Right margin in horizontal coordinates. (From the left side of the screen to the 
right margin.) 

4 Justification - It may have four values: O=left, 1=center, 2=right, and 3=full. 

5 Number of tabs present from zero to ten. 

6-7 Spacing - In order to get the spacing from this word, spacing = 1+(n/ 2). The 
high bit is set if six lines per inch is active. 

8-9 The indentation of the first line as a horizontal coordinate. (From the left side of 
the screen to the first line indentation.) 

10-29 The tab array. It contains ten integer values which are the horizontal 
coordinates for the tabs. (Number of pixels between the left side of the screen 
and the tab.) Decimal tabs are negative. 

30-33 Unused. 


Picture Paragraph: A picture paragraph starts with a rectangle containing the picture size, 


followed by a standard Quickdraw picture. A page break is also a picture, but 
the ASCII characters for MAGICPIC replace the rectangle at the start of the 
picture. 


Compression Scheme - !n the document's resources is a resource of type STR with the 


ID #700. It contains the fifteen most common letters in the language of the 
MacWrite that created the document. The compressed paragraph isa 
collection of nibbles (four bits, or half-bytes). If a letter is one of the fifteen most 
common then it only takes a nibble to represent. Otherwise, a nibble equal to 
fifteen signifies that the letter following is a byte of standard ASCII. (Important 
note: the ASCII byte will not necessarily be aligned on a byte boundary.) For 
example, if the first five most common letters in the language are M, c, W, i, and 
e then the sequence of nibbles 1, 15, 6, 1, 2,3, 15, 7, 2, 4, 15, 7, 4, 5 spells out 
MacWrite (assuming, of course, that the letters a, r, and t are not in the list of 
most common letters). 
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Font Mapping - In the document's resources is a resource of type STR with the ID #801. 
It contains a mapping of fonts to font resource IDs and information on real fonts. 
This resource begins with a word which represents the number of fonts in the 
document. That word is followed by a series of words, one for each font, which 
contain the font number of the font in the system file the document was last 
saved under. These words are in order of appearance of the font in the font 
menu. These words are followed by a series of bytes, one for each font. The 
byte indicates which sizes of the font are contained in the system file. MacWrite 
supports fonts of sizes 9,10,12,14,18,24. Bit O of the byte is set if size 9 of the 
font is real, bit 1 if size 10 is real and so-on to bit 5, which is set if size 24 is real. 
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#13: MacWrite Clipboard Format 


See also: MacWrite Owner's Manual 
Scrap Manager: A Programmer's Guide 
Technical Note #11--Memory Based MacWrite File Format 
Technical Note #12--Disk Based MacWrite File Format 


Written by: Encore Systems 13-February-85 
Modified by: Harvey Alcabes 12-April-85 


This note describes the clipboard format for all versions of MacWrite. 


This note describes the MacWrite clipboard format. MacWrite's custom resource type 
is called 'MWRT'. For more general information involving the desk scrap, please refer 
to the Scrap Manager section of Inside Macintosh. 


lf the clipboard contains a single picture, then only the standard ResType 'PICT' is 
used. If it contains any text paragraphs, then that text will be written out using the 
standard ResType ‘TEXT’. Note that this type consists of standard ASCII characters, 
and formatting information is not included. The 'MWRT custom scrap is written out only 
if there is room in memory and on disk. 


'MWRT Variables - Each 'MWRT’ ResType begins with... 


Bytes ltem 

0-1 Number of paragraphs in the clipboard. 

2 Start Word - Boolean : TRUE if the start of the clipboard contents 
begins on a word boundary. | 

3 End Word - Boolean : TRUE if the end of the clipboard contents 
finishes on a word boundary. 

4 Start Paragraph - Boolean : TRUE if the start of the clipboard 


contents begins on a paragraph boundary. 
5 End Paragraph - Boolean : TRUE if the end of the clipboard 
contents finishes on a paragraph boundary. 
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'MWRT Array - Following the 'MWRT' variables, is the 'MWRT array. For every 
paragraph in the clipboard, there is an element in this array which 


consists of: 
Bytes ltem 
0-1 Length of the paragraph data in bytes (n). 
2-3 Paragraph Type - A positive value indicates text, a negative value 


means a picture, and zero is used if the paragraph is a ruler. 

4-(n+4) Paragraph Data - The paragraph data is stored as in MacWrite itself, so 
please refer to the MacWrite File Format Technical Notes (numbers 11 
and 12). Note that the decompressed text paragraphs are stored the 
same for all versions of MacWrite. 
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#14: The INIT 31 Mechanism 


See also: Inside Macintosh: The Resource Manager 
Inside Macintosh: The Device Manager 
Technical Note #71: Finding Drivers in the Unit Table 


Written by: Bryan Stearns March 13, 1986 


The Macintosh Plus system software contains a mechanism (known as INIT 
31) which allows boot-time driver initialization without modification to the 
System File. This note describes INIT 31 and how it's used. 





Ever since the first Macintosh System Update, Apple has tried to dissuade developers 

from writing to the System File. We found that some third-party installation utilities 

tended to somehow corrupt the System File, making it difficult for us to update our 
system software there. 


Since then, we've been working on ways to help developers avoid writing to the System 
File, such as Font/DA Mover, the Installer and INIT 31. 


What is INIT 31? 


In the Macintosh Plus System File, we added a new INIT resource (INIT resources are 
resources containing code which are loaded and run at boot time by the system startup 
code). INIT number 31 is one of the last to be executed by the startup code. St looks at all 
the other files in the System folder for files whose type is "INIT"; when it finds one, it 
opens it and checks for resources of type INIT. If any exist, it loads and JsR's to them, 
before closing the resource file and looking for the next one. 


This allows you to create a single file, containing your driver and INIT, which a user can 
simply drag into the System folder without having to run an installer. To un-install your 
software, the user simply drags your software out of the System folder. 


How_to write an INIT 31 

INIT resources are resources containing executable code, beginning with the first byte 
of the resource. An INIT resource is not locked down by the code that loads it, so the 
"locked" bit in its resource attributes should be set. Also, if it is desired that the INIT's 
code remain in memory “permanently”, the INIT must call DetachResource to detach 
itself, so that it will not be disposed of when its resource file is closed. 
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Boot-time Driver Number Arbitration 

Any old-style INIT resource will probably work correctly, unmodified, if placed in an 
INiT-type file as described above. Ideally, however, INITs which load drivers must be 
careful not to open a driver whose ID is already in use by another driver or desk 
accessory. . 


This is a two-stage process. First, the unit table must be checked to see that a given unit 
number is not being used by an open driver (see Technical Note #71). Then, the 
System file must be checked to make sure that there isn't an unopened driver with that 
resource ID. 


Once an unused number is found, your driver must be renumbered so that OpenDriver 
will use the proper unit number. The following sequence of steps will accomplish this: 


e Use GetNamedResource to load your driver . 

* Use GetResiInfo and SetResInfo to change your driver's resource ID 
(without changing its other resource attributes). 

e Use GetResFileAttrs and SetResFileAttrs to clear the 
mapChanged bit of the resource file's map attributes, so that the change 
in resource ID will not be permanent (note that this should only be done 
if no other modifications to the resource file are made at boot time, as is 
the usual case). 

¢« Use OpenDriver to open your driver by name. 


Allocating “Permanent” Memory 
The memory space in the system heap is too valuable to waste. So, if the software you 


install at boot time needs more than 1K of "permanent" space, it shouldn't be kept in the 
system heap. 


You can allocate "permanent" space (that is, space that will remain undisturbed across 
application launches, until the machine is rebooted) at boot time by subtracting the 
amount you need from the value in BufPtr (the longword at $10c), then replacing that 
value in BufPtr. This low-memory globai points at the highest usable address in 
memory (normally just below the primary screen and sound buffers). The Segment 
Loader Launch procedure builds the global environment for each application 
immediately below the address in BufPtr. 


Note that if you allocate space in this manner, it cannot be moved, enlarged, or 
deaillocated. If you allocate too much space in this manner, the performance of some 
applications may degrade (because the more space you allocate, the less is available 
in the application heap), and in extreme cases may cause crashes. The secondary 
screen and sound buffers may not be used if this technique is used. 


Also, you must not assume that BufPtr will continue to point at the space you allocated 
(because additional space may be allocated by others). If you have a driver, you can 
keep a pointer to your space among your dCtlStorage variables. If you have an 
external file system, your pointer in ExtFSHook will probably be enough (a future 
Technical Note will discuss external file systems in detail). 
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#15: Finder Update 
See also: Macintosh Owner's Manual 


Written by: Harvey Alcabes 12-April-85 


Apple is releasing Finder 4.1. This note describes some features included in 
the new Finder. 


Finder 4.1 


Apple is releasing an enhanced Finder. Finder 4.1, the new version, will be included in 
the May Software Supplement. The software will be available as a free upgrade to all 
Macintosh users, and will ship with new Macintosh systems beginning in May. It will also 
ship with the new disk-based MacWrite, the improved MacPaint, and the Macintosh and 
MacWorks XL system disks. 


The new Finder furnishes incremental performance improvements to Macintosh, making it 
even more powerful as a business machine. Changes to the Finder should not affect 
applications. The enhanced Finder includes the following features: 


° Faster operation - you can perform operations such as launching and quitting 
applications and copying disks more quickly. 


° Access to more files - up to 500 files can be handled on a disk drive. This 
benefits hard disk users. 


° MiniFinder - the MiniFinder allows you to move quickly between twelve 
applications or files that you use most frequently. Designed for experienced Macintosh 
users, the MiniFinder was optimized for speed and therefore doesn't support some of 
the usual Macintosh features such as desk accessories. 


° "New Folder" command - no more need for the Empty Folder on the desktop, as a 
new folder can be created by choosing this menu command. 


° "Shutdown" command - restarting with a different startup disk is easier. The disk 
in use is ejected and the Macintosh restarts (Macintosh XL turns the power off, but not 
on again). 


° Improved directory handling - directory windows can be arranged by icon, name, 
size, date or kind. The files can be manipulated (e.g. copied or arranged} and then 
printed. 
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#16: MacWorks XL 


See also: MacWorks XL Owner's Manual 
Written by: Harvey Alcabes 11-May-85 
Mark Baumwell 


Apple is releasing MacWorks™ XL. This note describes some features of 
this new version of MacWorks. 





MacWorks is the software which allows a Macintosh XL (formerly called 
the Lisa 2/10) or any other Lisa 2 system to run Macintosh software. A 
copy of the released version of MacWorks XL will be included in the final 
update to the Software Supplement in May. Supplement purchasers 
received a MacWorks XL pre-release dated 12/10/84 in the December 
Software Supplement mailing. Here's a quick summary of the features of 
MacWorks XL: 


° Direct startup from the hard disk. If a Macintosh XL, Lisa 2/5, 
or Lisa 2/10 has a hard disk dedicated to Macintosh software, the system 
boots up directly from power on. 

° For those Lisa systems with a shared disk, the Macintosh 
environment can now be started with one diskette, like the other 
Macintoshes. 


° Support of AppleTalk™ Personal Network and the LaserWriter, 
in addition to future Macintosh Office products. 
. Support of the parallel version of the Apple Dot Matrix Printer, 


for those Lisa customers interested in using their printer with the 
Macintosh environment. 


Users of graphics-oriented applications who are concerned about the 
aspect ratio of the Macintosh XL screen (which currently displays 364 

rows of 720 rectangular pixels) may chose to purchase the Macintosn XL 
Screen Modification Kit (Apple part number A680001). This kit is 

expected to be available through Apple dealers in June and will include a 
copy of MacWorks XL along with parts for a modification to the Macintosh 
XL hardware. A Macintosh XL with the modified hardware and MacWorks XL 
software will display square pixels, producing the same aspect ratio as 

the 128K and 512K Macintoshes. The 32 KBytes of Macintosh XL screen 
memory will be used to display 431 rows of 608 square pixels. 
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A Macintosh XL modified in this way will no longer be able to run Lisa 
software such as the Workshop development system or the Lisa 7/7 Office 
System. Also, it will no longer have an imbedded serial number. The 
hardware modification will be an option only available through dealers. 
The MacWorks XL software should work properly on modified and 
unmodified machines. 


Reading Machine Information 
The word at location $400008 contains a ROM version number. On a 128K 
or 512K Macintosh it contains $0069. The version number of MacWorks 1.0 
(the version released in 1984) is $70. The version number of MacWorks XL 
is $81 (note that the December pre-release had the version number $80. 
Lisa Pascal users can identify the machine and ROM version number by 
calling the following routine (found in intrfc/OSIntf): 

PROCEDURE Environs (VAR rom, machine: INTEGER); 
where machine will be one of the constants macMachine or macXLMachine. 
An application should not assume anything about the screen size or aspect 
ratio based on the hardware on which it is running. If aspect ratio 
information is needed the program should use the words in low memory at 
ScrVRes ($102) and SerHRes ($104), which contain the screen dots per 
inch vertically and horizontally. A Lisa Pascal routine will be included in 
the May Software Supplement to return these values. It will be declared 
as follows: 

PROCEDURE ScreenRes (VAR SerVRes, ScrHRes: INTEGER); 
Summary 
The following table summarizes the information above; note that values 
preceded by a "$" are hexadecimal, other values are decimal. 


ROM Dots per inch Pixels on screen 
version Vertical Horizontal Vertical Horizontal 
number (ScrVRes) (ScrHRes) 

($400008) ($102) ($104) 
Macintosh 128 $0069 72 72 342 512 
Macintosh 512 $0069 72 72 342 512 
MacWorks (1.0) $70FF 60 90 364 720 
MacWorks XL 
unmodified hardware $81FF 60 90 364 720 
modified hardware $81FF 72 72 431 608 
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#17: New Low-Level Printer Driver Calls 
See also: The Print Manager 


Written by: Ginger Jernigan April 14, 1986 





This Technical Note describes new low-level calls added to the Print 
Manager. 





The Prct1Call printer controls (iWhichctl = 7) have been expanded to match the 
high level Printing Manager calls as follows: 


e The controls LPrReset and l1PrPageEnd have been renamed 1PrDocOpen 
and 1PrPageClose. 


¢ Two new controls have been added: 1PrPageOpen and 1PrDocClose. 


These calls are needed for low-level printing to a LaserWriter or an ImageWriter 
connected over AppleTalk. 


The new values are as follows: 


CONST 1PrDocOpen = $00010000; {reset printer; on some printers} 
{ low-order byte indicates # copies 
{ to print} 
1PrPageOpen =  $00040000; {initialize printer software for a} 
{ new page} 
1PrPageClose = $00020000; {end page} 
l1PrDocClose = $00050000; {close the printer connection and} 


{ release the driver buffers} 


The 1PrLineFeed parameter is unchanged. Note that all Apple printer drivers now use 
these calls properly, or ignore them if not applicable. lf you are using only low-level 
printer calls you should always include these. 


Note: Using the low-level print driver calls together with high-level calls violates the user 


interface guidelines, in that the user will not obtain the results he/she expects from the 
printer dialogs. 
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#18: Text Edit Conversion Utility 


see also: TextEdit: A Programmer's Guide 
Macintosh Memory Management: An Introduction 


Written by: Harvey Alcabes 10-April-85 


Text sometimes must be converted between in TextEdit records and Pascal 
strings. This notes illustrates a way to do this conversion using Lisa Pascal. 


Text contained in TextEdit records sometimes must be passed to routines which expect a 
Pascal string of type Str255 (a length byte followed by up to 255 characters). The following 
Lisa Pascal unit can be used to convert between TextEdit records and Pascal strings: 


UNIT TEconvert; 
{SR-} 


INTERFACE 


USES {$U-} 
{$U Obj/Memtypes} Memtypes, 
{$U Obj/QuickDraw} QuickDraw, 
{SU Obj/OSIntf}  OSIntf, 
{SU Obj/TooliIntf£} Toollintf; 


{General utilities for conversion between TextEdit and strings} 


PROCEDURE TERecToStr (hTE: TEHandle; VAR Str: Str255); 
{TERecToStr converts the TextEdit record pointed 
to by hTE to the string Str. If necessary the text 
will be truncated to 255 characters. } 


PROCEDURE StrToTERec (Str: Str255; HTE: TEHandle); 
{StrToTERec converts the string Str to the TextEdit 
record pointed to by hTE. } 


IMPLEMENTATION 


PROCEDURE TERecToStr (hTE: TEHandle; VAR Str: Str255); 
BEGIN 
GetIText (hTE*®* .nText, Str); 
END; 


PROCEDURE StrToTERec (Str: Str255; hTE: TEHandle); 
BEGIN 
TESetText (POINTER(ORD4 (@Str)+#1), ORD4(length(Str)), NTE); 
END; 


END. { of unit TEconvert } 
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#19: How To Produce Continuous Sound Without "Clicking" 


See also: The Sound Driver 
The File Manager 
The Vertical Retrace Manager 


Written by: Ginger Jernigan 4/18/85 


This technote describes how to use the Sound Driver to produce continuous 
sound without the "click" that the driver produces when it starts a sound. 


If you have tried using the Sound Driver to produce sound you probably noticed that 
one StartSound call produces sound for a comparatively short time. So, to produce 
longer sounds the obvious thing to do is to make consecutive calls to StartSound. This, 
however, produces an annoying "click" everytime StartSound is executed. This 
technote describes how to use the Sound Driver to produce continuous sound without 
the "click", and provides a little more background information about how the Sound 
Driver works. 


How Does The Sound Driver REALLY Work 


In order to better understand how to modify the output of the Sound Driver, we need to 
know more about how sound is produced. For this discussion we will use the free form 
synthesizer as our example. The process used for the other synthesizers is very similar. 


To produce sound, the first thing we do is set up the sound buffer. For the free form 
synthesizer this consists of the the FFSynthRec, which includes the following fields: 


Mode: The mode for the free form synthesizer is FFMode. 
Count: Count is a fixed point number used for sampling the wave form. 
Waveform: This is the array of values that define the wave form. 


To set up the buffer, use the example in the Sound Driver section of Inside Macintosh, 
page 11. Once you set up your buffer you then call Startsound. StartSound will in turn 
set up a parameter block where iobuffer contains your buffer (in our case 
FFSynthRec); the iorefnum is -4; iocompletion points to your completion routine; and 
iloreqcount is equal to the size of your buffer. Once the parameter block is set up it 
then calls the Write trap. (If you are using assembly language or a third party 
development system that doesn't support StartSound, these are the steps you would 
take to start the sound yourself.) 
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When the Sound Driver gets the parameter block it reads the mode from the buffer to 
find out which synthesizer to use to interpret the buffer. It then installs itself into the 
Vertical Retrace queue, samples the waveform according to the count given, and then 
loads the specified bytes into the high (even) bytes of the sound/disk speed buffer. As it 
indexes through the waveform array using count it increments the ioactcount field in 
the parameter block and checks it against the toreqcount to make sure it doesn't 
exceed the wave form array. If the ioactcount and ioreqcount aren't equal on the 
next vertical retrace, then it fills the buffer again. If they are equal and the buffer isn't 
filled, the rest of the buffer is filled with zeros. 


How To Avoid The Embarassing "Click" 


The click happens after the _Write call occurs, while the driver is setting up for the 
production of sound. Therefore, the trick is to make only one call to start the sound, then 
change the information in the paramater block while the Sound Driver is still producing 
sound. 


The first step is to take care of the parameter block setup and the PBWrite (_Write) cali 
yourself, instead of letting Startsound do it for you. The reason is that you need to have 
easy access to the parameter block in order to change the ioactcount field. The Sound 
Driver uses ioactcount to keep track of where it is in the sound buffer. So, when we 
want the sound to start over again, instead of calling _Write again we fool the Sound 
Driver into thinking it is actually starting at the beginning of the buffer by setting 
joactcount to 0. 


To set up the sound buffer and the parameter block here's an example. Again, we are 
using free form sound. 


{$U-} 
{$R-} 
{$M+} 
{SL+} 
Program Soundtest; 


{$L~} 

uses 
{$U Ob j/MemTypes 
{$U Ob j/QuickDraw 
($U Ob3/O0SIntf£ 
{$U Obj/Toolintf 
{SU Obj/PackIntf 
($U Obj/SaneLib 

($L+} 


MemTypes, 

QuickDraw, 

OSIintf, 

TOGLINAtE, 

PackIintf, 

SANE; { Just in case we want to do any SANE stuff } 


w y y M O 


VAR myHandle ; handle; 
MyFFPtr : FFSynthPtr; 
Buffsize : integer; 
ip]? integer; 
Parmbiock : parmblkptr; 
err : Ooserr; 


BEGIN 
FlushEvents (everyevent, 9); 
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{ First we set up the sound buffer information } 


Buffsize := 30000; { The total size of the buffer is 30000 } 
_myHandle := NewHandle(buffsize); { Make a new handle of that size } 

HLock {(myhandle) ; { Lock it. We don't want it to move on us } 

MyFFPtr := FFSynthPtr( MyHandle* }; { Force a type coercion on the contents of the 


handle to an FFSynthPtr } 
Set the mode to free form synthesizer } 


Am 


MyFFPtr^.mode := FFMode; 


MyFFPtr*.Count := $00010000; { Set the count to 1 - remember this is in 
fixed-point notation } 
j := 0; { The waveform is zero based } 


The -6 is for mode and count, and -l is because 
we're zero based } 


WHILE j<=buffsize-7 DO BEGIN 


atm, 


FOR i := 0 to 255 DO BEGIN 
MyFFPtr“.wavebytes[j] := i; 


n 


Stuff the waveform with values } 


3 := jri; { Increment wave index } 
END; 
END; 
Set SoundVol (6) ; { Set the sound volume } 


{ Then we allocate the parameter block } 

ParmBlock := ParmBlLkPtr{ NewPtr( SizeOf( ParamBlockRec ))); 

WITH Parmblock*® DO BEGIN { And set up the parameter block with ... } 
iocompletion := nil; No completion routine } 
iorefnum := ~4; Refnum is -4 as per Inside Macintosh } 
Llobuffer := ptr( MyFFPtr }; The buffer is set to point to my sound buffer } 
Lloreqcount := buffsize; The required count is set to the size of the 

buffer } 


{ 
{ 
{ 
{ 


END; 
err := PBWrite(Parmblock,true); { OK - now write it asynchronously} 


After this point the Sound Driver starts filling the buffer and sound is produced as 
discussed above. The sound is produced asynchronously in order to allow our 
program to keep on running during the sound generation. To restart the sound you 
want to change the ioactcount after the buffer has been filled (and after the Vertical 
Retrace task has incremented ioactcount) and before the last pass at filling the 
sound/disk speed buffer. 


The trick is to make sure the change to ioactcount happens at the right time. If you 
change it too early, then the Vertical Retrace task will increment it after you have 
changed it, thus resetting it to where it was before. If you change it too late it will finish 
the waveform and stop the sound whether you want it too or not. The best way to take 
care of this timing problem is to install your own Vertical Retrace task in the queue 
before or after the sound task. The task would look something like this: 


IF ParmBlock*.iocactcount >= 29960 THEN BEGIN 


{the 29960 is from the formula (count*370) *Trunc(waveform/ (count*370)). This should 
be before the last pass through the waveform. } 
ParmBlock*.ioactcount := 0; 
MyFFPtr*®.count := MyFFPtr*.count + $00000500; { Let's increment the count for 
fun} 
END; 


lf the routine is in the vertical retrace queue then you avoid the “critical section”. This is 
when the sound code and your code are trying to change the same value at the same 
time. You want to avoid this. Really. 
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Changing The Sound Information 


Notice that we also changed the count parameter in the buffer. Since ioactcount is 
now 0 it will begin at the beginning of the waveform the next time is needs to stuff the 
sound/disk speed buffer. Since we have changed the count(sampling rate), it will use 
the new value to sample the waveform on the next pass. 


if you need to change the values in the waveform, there are two methods. The first is to 
change the current waveform. To do this, you would, for example, check to see if 
joactcount is half of ioreqcount, and start stuffing at the beginning of the buffer. Be 
careful, though, because you can stuff the waveform faster than the values are 
sampled. Then, before the last pass at filling the sound/disk speed buffer change the 
ioactcount so it will start at the beginning of your new wave form. 


The second method is to fill a different waveform while you are producing sound and 


when you change ioactcount, you assign the second buffer into iobuffer. Make sure 
the mode and count are correct in the second buffer. 
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#20: Data Servers on AppleTalk 


See also: The AppleTalk Manager: A Programmer's Guide 
Inside LaserWriter 


Written by: Bryan Stearns 29-Apr-85 





Many applications could benefit from the ability to share common data 
between several Macintoshes, without requiring a file server. This Technical 
Note discusses one technique for managing this AppleTalk communication. 





There are four main classes of network "Server" devices: 


Device Servers, such as the Apple LaserWriter, allow several users to share a 
single hardware device; other examples of this (currently under development by third 
parties) are modem servers and serial servers (to take advantage of non-intelligent 
printers such as imagewriter). 


File Servers: devices which support file access operations over the network. A user 
station sends high-level requests over the network (such as "Open this file", "Read 137 
bytes starting at the current file position of this file", "Close this file", etc.). Apple has 
introduced a file server, to be available later this year; the protocol that the file server 
will use is not ready for publication yet (we hope to make it available to developers 
through mailings and seminars this summer). There are also several third-party 
developers working on file servers. 


Block Servers: devices which answer to block requests over the network. These 
requests impart no file system knowledge about the blocks being passed, i.e., the 
server doesn't know which files are open by which users, and therefore cannot protect 
one user's open file from other users. Examples of this type of server are available now 
from third-party developers. 


Data Servers: devices which answer to requests at a higher level than file servers, 
such as "Give me the first four records from the database which match the following 
search specification". This note directs its attention at this type of server. 


A data server is like a file server in that it responds to intelligent requests, Dut the 
requests that it responds to can be more specialized, because the code in the server 
was written to handle that specific type of data. This has several added benefits: user 
station processing can be reduced, if the data server is used for sorting or searching 
operations; and network traffic is reduced, because of the specificness of the requests 
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passed over the network. The data server can even be designed to do printing (over 
the network to a LaserWriter, or on a local Imagewriter), given that it has the data and 
can be directed as to the format in which it should be printed. 


ATP: The AppleTalk Transaction Protocol 


ATP, the assured-delivery AppleTalk Transaction Protocol, can be used to support all 
types of server communications (the LaserWriter uses ATP for its communications)). 
Here is a possible scenario between two user stations ("Dave" and "Bill") and a data 
server station ("OneServer", a server of type "MyServer"). We've found that the 
“conversational” analogy is helpful when planning AppleTalk communications; this 
example is therefore presented as a conversation, along with appropriate AppleTalk 
Manager calls (Note that no error handling is presented, however; your application 
should contain code for handling errors, specifically the "half-open connection" 


problem described below). 


Establishing the Connection 


Each station uses ATPLoad to make sure that AppleTalk is loaded. The server station, 
since it wants to accept requests, opens a socket and registers its name using 
NBPRegister; The user stations use NBPLookUp to find out the server's network 
address. This looks like this, conversationally: 


Server: “I'm ready to accept 
requests!" 


Dave: “Any 'MyServers' 
out there?” 


Dave: "Hey, MyServer! What 
socket should | talk to you 
on?" 


Bill: "Any ‘MyServers' 
out there?” 


Bill: “Hey, MyServer! What 
socket should | talk to you 
on?” 


Server: "Hi, Dave! Use Socket N" 


Server: "Hi, Bill! Use socket M” 
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ATPLoad 
OpenSocket 
NBPRegister 
ATPGetRequest 
ATPGetRequest 
ATPGetRequest 


ATPLoad 
NBPLookup 


ATPRequest 


ATPLoad 
NBPLookup 


ATPRequest 


ATPOpenskt 
ATPResponse 
ATPGetRequest 


ATPOpensSkt 
ATPResponse 
ATPGetRequest 
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Opens AppleTalk 

Creates socket 

Assigns name to socket 

queue a few asynchronous 
calls, to be able to handle several 
users 


Opens AppleTalk 
look for servers, finds OneServer 


Ask the server which socket to 
use for further communications 


Opens AppieTalk 
look for servers, finds OneServer 


Ask the server which socket to 
use for further communications 


Get a new socket for talking to Dave 
Send Dave the socket number 
Replace the used GetRequest 


Get a new socket for talking to Bill 
Send Bill the socket number 
Replace the used GetRequest 


Data Servers on AppleTalk 


From this point on, the server knows that any requests received on socket N are from 
Dave, and those received on socket M are from Bill. The conversations continue, after 
a brief discussion of error handling. 


Half-open Connections 


There is a possibility that one side of a connection could go down (be powered off, 
rebooted accidently, or simply crash) before the connection has been officially broken. 
if a user station goes down, the server must throw away any saved state information 
and close that user's open socket. This can be done by requiring that the user stations 
periodically "tickle" the server: every 30 seconds (for example) the user station sends a 
dummy request to the server, which sends a dummy response. This lets each side of 
the connection know that the other side is stiil “alive”. 


When the server detects that two intervals have gone by without a tickle request, it can 
assume that the user station has crashed, and close that user's socket and throw away 
any accumulated state information. 


The user station should use a vertical-blanking task to generate these tickie requests 
asyncronously, rather than generating them within the GetNextEvent loop; this avoids 
problems with long periods away from GetNextEvent (such as when a modal dialog 
box is running). This task can look at the time that the last request was made of the 
server, and if it's approaching the interval time, queue an asynchronous request to 
tickle the server (it's important that any AppleTalk calls made from interrupt or 
completion routines be asynchronous). 


lf a user station's request (including a tickle request) goes unanswered, the user 
station should recover by looking for the server and reestablishing communications as 
shown above (beginning with the call to NBPLookUp). 


More information about half-open connections can be found in the Printer Access 
Protocol chapter of Inside LaserWriter, available for $75 from Apple Computer, 467 
Saratoga Ave Suite 621, San Jose, CA 95129. 


Using the connection 


The user stations Dave and Bill have established communications with the server, 
each on its own socket (note that the user stations have not had to open their own 
sockets, or register names of their own, to do this - the names we're using are merely 
for explanational convenience). They are also automatically tickling the server as 
necessary. 


Now the user stations make requests of the server as needed: 


Bill: "I'd like to use the sales ATPRequest Bill opens a database. 
figures for this year." 


Server: "Ok, Bill.” ATPResponse The server checks to make sure that 
no one else is using that database. 


Technical Note #20 page 3 of 4 Data Servers on AppleTalk 


Dave: = "Hey, Server - I'm still here!" 


Server: “Ok, Dave.” 
Bill: “Please print the figures 
for January thru June.” 


Server: “Ok, Bill." 


Dave: “I'd like to use the sales 
figures for this year." 


Server: “Sorry, Dave, | can't do that. 
Bill is using that database.” 


Closing the Connection 


ATPRequest 


ATPResponse 


ATPRequest 


ATPResponse 


ATPRequest 


ATPResponse 


Dave notices that the interval time is 
approaching, and makes a tickle 
request. 


The server resets its “last time | heard 
from Dave". 


Bill asks for specific data. 

The server does a database search 
sorts the results, and prints them 
on a local Imagewriter. 

Dave opens a database. 


The server finds that Bill is using that 
data. 


The user stations continue making requests of the server, until each is finished. The 
type of work being done by the server determines how long the conversation will last: 
since the number of sockets openable by the server is limited, it may be desireable to 
structure the requests in such a way that the average conversation is very short. It may 
also be necessary to have a (NBP named) socket open on the user station, if the server 
needs to communicate with the user on other than a request-response basis. Here is 
how our example connections ended: 


Dave: “Thank you, server, l'm done ATPRequest 


now. You've been a big help.“ 


Server: "Ok, Dave. Bye now.” 


ATPResponse 
ATPCloseSkt 


ATPCloseSkt 


Dave tells the server he's finished. 


The server kisses Dave goodbye. 
After the Response operation 
completes, the server closes 

the socket Dave was using. It also 
notices that Bill hasn't sent a request 
in more than two intervals, and closes 
Bill's socket, too. 


The user station can forget about the socket it was using on the server; if it needs to talk 
with the server again, it starts at the NBPLookUp (just in case the server has moved, 


gone down and come up, etc.). 
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#21: QuickDraw’s Internal Picture Definition 


See also: QuickDraw 
Programming in Assembly Language 


Written by: Ginger Jernigan April 24, 1985 
Modified: Ginger Jernigan June 20, 1986 





This Technical Note describes the internal format of the QuickDraw picture 
data structure. | 





This Technical Note describes the long awaited internal definition of the QuickDraw 
picture. The information given here is meant for DEBUGGING PURPOSES ONLY. It 
should not be used to write your own picture bottleneck procedures; if we add new 
objects to the picture definition, your program will not be able to operate on pictures 
created using standard QuickDraw. Your program will not know the size of the new 
objects and will, therefore, not be able to proceed past the new objects. (What this 
ultimately means is that pictures will not be downward compatible; you can't process a 
new picture with a old bottleneck proc.) 


Before listing the opcodes a little information is in order. An opcode is a number that 
DrawPicture, for example, uses to determine how to draw that particular object in the 
picture, and how much data is associated with it. The following list gives the opcode, 
the name of the object, the associated data, and the total size, in bytes, of the opcode 
and associated data. To better interpret the sizes, please refer to page 4 in the 
“Programming in Assembly Language” chapter of Inside Macintosh. For types not 
described there, here is a quick list: 


opcode byte 

point long 

0..255 byte 
 —128..127 byte 

rect 8 bytes 

poly 11+ bytes 

region 10+ bytes 

fixed point number long 

pattern 8 bytes 


Each picture definition begins with a picsize (word), then a picframe (rect), and 
then the picture definition, which consists of a combination of the following opcodes: 
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Opcode Name Addition at Total Size (bytes) 
00 NOP none 
01 clipRgn rgn 1+rgn 
02 bkPat pattern 9 
03 txFont font (word) 3 
04 txFace face (byte) 2 
05 txMode mode (word) 3 
06 spExtra extra (fixed point) 5 
07 pnsize pnSize (point) 5 
08 pnMode mode (word) 3 
09 pnPat pattern 9 
0A thePat pattern 9 
0B ovsize point 5 
0C origin dh, dv (word) 5 
oD txSize size (word) 3 
OE fgColor color (long) 5 
OF bkColor color (long) 5 
10 txRatio numer (point), denom (point) 9 
11 picVersion version (byte) 2 
20 line pnLoc ( point ), newPt ( point ) 9 
21 line from newPt ( point ) 5 
22 short line pnLoc ( point ), dh, dv (-128..127) 7 
23 short line from dh, dv (-128..127) 3 
28 long text txLoc ( point ), count (0..255), text 6+text 
29 DH text dh (0..255), count (0..255), text 3+text 
2A DV text dv (0..255), count (0..255), text 3+text 
2B DHDV text dh, dv (0..255), count (0..255), text 4+text 
30 frameRect rect 9 
31 paintRect rect 9 
32 eraseRect rect 9 
33 invertRect rect 9 
34 fillRect rect 9 
38 frameSameRect rect 1 
39 paintSameRect rect 1 
3A eraseSameRect rect 1 
3B invertSameRect rect 1 
3C filSameRect rect 1 
40 frameRRect rect, ovaiwidth, ovalHeight 19 
41 paintRRect rect, ovaiwidth, ovalHeight 13 
42 eraseRRect rect, ovalwidth, ovalHeight 13 
43 invertRRect rect, ovalwidth, ovalHeight 13 
44 fillRRect rect, ovalwidth, ovalHeight 13 
48 frameSameRRect rect 1 
49 paintSameRRect rect 1 
4A eraseSameRRect rect 1 
4B invetSameRRect rect 1 
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Opcode (cont.) Name_ Additional. Data Total Size (bytes) 


4C fillSameRRect rect 1 

50 frameOval rect 9 

51 paintOval rect 9 

52 eraseOval rect 9 

53 invertOval rect 9 

54 filiOval rect 9 

58 frameSameOval rect 1 

59 paintSameOval rect 1 

5A eraseSameOval rect 1 

5B invetSameOvai rect 1 

5C fillSameOval rect 1 

60 frameArc rect, startAngle, arcAngle 13 

61 paintArc rect, startAngle, arcAngle 13: * 

62 eraseArc rect, startAngle, arcAngle 13 

63 invertArc rect, startAngle, arcAngle 13 

64 fillArc rect, startAngile, arcAngle 13 

68 frameSameArc rect 1 

69 paintSameArc rect 1 

6A eraseSameArc rect 1 

6B invertSameArc rect 1 

6C fillSameArc rect 1 

70 framePoly poly 1+poly 

71 paintPoly poly 1+poly 

72 erasePoly paly 1+poaly 

73 invertPoly poly 1+poly 

74 fillPoly poly 1+poly 

78 frameSamePoly (not yet implemented) 1 

79 paintSamePoly (not yet implemented) 1 

7A eraseSamePoly (not yet implemented) 1 

7B invertSamePoly (not yet implemented) 1 

7C fillSamePoly (not yet implemented) 1 

80 frameRgn rgn 1+rgn 

81 paintRgn rgn 1+rgn 

82 eraseRgn rgn t+rgn 

83 invertRgn rgn 1+rgn 

84 filiRgn rgn 1+rgn 

88 frameSameRgn (not yet implemented) 1 

89 paintSameRgn (not yet implemented) 1 

8A eraseSameRgn (not yet implemented) 1 

8B inverttSameRgn (not yet implemented) 1 

8C fiiSameRgn (not yet implemented) 1 

90 BitsRect rowBytes, bounds, srcRect, dstRect, mode, 30+unpacked 
byteCount, unpacked bitData bitData 
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Opcode (cont.) 
91 
98 
99 


AO 
A1 


FF 
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Name. 
BitsRgn 
PackBitsRect 


PackBitsRgn 


shortComment 
longComment 


EndOfPicture 


Additionai Data 


rowBytes, bounds, srcRect, dstRect, mode, 
maskRogn, byteCount, unpacked bitData 
rowBytes, bounds, srcRect, dstRect, mode, 
byteCount & packed bitData for each row 
rowBytes, bounds, srcRect, dstRect, mode, 
maskRogn, byteCount & packed bitData for 
each row 


kind(word) 
kind(word), size(word), data 


none 
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Total Size (bytes) 


30+rgn+ 
bitData 
30+packed 
bitData 
30+rgn+ 
packed bitData 


3 
5+data 


1 
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#22: TEScroll Bug on Macintosh Plus 
See also: TextEdit 


Written by: Bryan Stearns April 21, 1986 





A change to TextEdit on Macintosh Plus causes the following problem: a call to 
TEScroll with no horizontal or vertical displacement (that is, both dh and dv set to 
zero) results in disappearance of the insertion point. Since such calls do nothing, they 
should be avoided: 


IF (dh <> 0) OR (dv <> 0) THEN TEScroll (dh, dv,myTEHand1le) ; 


Technical Note #22 page 1 oft TEScroll Bug on Macintosh Plus 





Macintosh Technical Notes Cy 


#23: Life After Font/DA Mover - How To Make Sure Your Desk Accessory Still 


Works 
see also: The Resource Manager 
Written by: Ginger Jernigan April 25, 1985 





This technical note describes how to make sure that your desk accessory siill 
works after being moved by the Font/Desk Accessory Mover. 





If you want your desk accessory to work properly after being moved by the Font/DA 
Mover, there are some eccentricities that you need to be aware of. When the Font/DA 
Mover (released version 1.2) moves a desk accessory, it will renumber your desk 
accessory if it has to to avoid conflicts in ID numbers. What this implies is that it will also 
renumber all of your desk accessory's owned resources. Before reading further, please 
read the "Resource IDs of Owned Resources” section of the Resource Manager. 


Now that you know all about owned resources and how their IDs are calculated, it 
becomes obvious that the renumbering done by the Font/DA Mover can be a problem. 
For example: If your desk accessory has an owned DLOG resource, and tries to call 
GetNewDialog with the ID you assigned to it originally, the Resource Manager may not 
find it. More than likely the ID has been changed because the desk accessory was 
moved, and the ID of the desk accessory has been changed. The solution is that every 
time your desk accessory references an owned resource, it must figure out at execution 
time the real ID of the resource according to the current driver resource ID. You have no 
way of knowing ahead of time whether the ID has been changed. 


An additional problem is that of ID references embedded in other resources, such as the 
reference to a DITL within a DLOG or ALRT resource. When the desk accessory ID gets 
changed, the ID of the DITL changes, but the ID of the DITL referenced in the DLOG 
doesn't. The Font/DA Mover does go back and fix some instances it suspects might be a 
problem, as in the above case. The list of cases where the Font/DA Mover fixes the 
references for you are listed below. 


However, if you have resources that contain references to resources other than those 
listed below, such as references to a CDEF you've defined, your desk accessory will 
have to compute the new ID from its current driver ID, then fix any references itself. For 
example, if the Font/DA Mover didn't fix the DLOG reference to the DITL(which it actually 
does), your desk accessory, before calling GetNewDialog, would do the following: 
compute the ID of the DLOG resource; call GetResource to get the DLOG; compute the 
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ID of the DITL; and check to see if the ID referenced in the DLOG is the same as the 
actual ID of the DITL. If they are different, the desk accessory fixes the DLOG, and 
updates the resource file. It can then call GetNewDialog without problems. 


Unfortunately, there is one common case that was (erroneously) not implemented in the 
release version of the Font/DA Mover. At the beginning of a MENU resource is the ID of 
the resource itself. This ID is used by the Desk Manager to determine if you should get 
an accMenu call if this menu is selected. The problem is that the Font/DA Mover fixes 
the resource ID in the Map, but not in the resource data itself. So, if you use GetMenu to 
get an owned MENU resource, you need to patch the first word pointed to by the handle 
returned with the actual resource ID of the MENU. 


As a rule of thumb, before you ship a desk accessory try moving it around to several 
disks that have different numbers of desk accessories on them. If one of the copies 
doesn't work, then there is something wrong with the way you are handling your owned 
resources. 


The resource back-patches currently implemented in the Font/DA Mover are": 
1. DLOG/ALRT reference to DITL 

2. DiTL references to ICON, PICT, CTRL 

3. MENU reference to MDEF 


* Anything not on this list has to be fixed by the desk accessory. 


By the Way... Before the Font/DA Mover, desk accessories could have an ID in the 
range 12 to 31. Now, and in the future, desk accessories can only have IDs in the range 
12 to 26. The Font/DA Mover will only assign numbers in this range. Numbers 27 thru 
31 are reserved for dynamic allocation of IDs at runtime for disk drivers, mail servers, 
etc. 
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#24: Available Volumes and Files 


See also: File Manager Programmer's Guide 

Written by: Bryan Stearns 26-Apr-85 
Modified by: Bryan Stearns 05-May-85 
Modified by: Bryan Stearns 15-Oct-85 





Standard File lets the user select one file from any available volume; it is 
sometimes necessary for the application itself to find out which volumes and 
files are present. This Technica! Note gives the proper method of 
accomplishing this. 


$$ 


There is a little-noticed feature of the low-level file manager call PBGetVinfo (_GetVInfo 
for you assembly-language programmers) which allows specification of a “volume 
index" to select the volume. This volume index selects the N-th volume in the VCB 
queue; the following function uses PBGetVInfo to find out about a given volume. 


{ * 
* GetIndVolume: return the name and volume reference number of a volume, 
* specified by whichVol. 
ai, 
FUNCTION GetIndVolume (whichVol:INTEGER; VAR volName: Str255; VAR volRef: 
INTEGER): OSErr; 
VAR volPB: ParamBliockRec; 
anErr: OSErr; 


BEGIN 

WITH volPB DO BEGIN {makes it easier to fill in!} 
ioNamePtr := @volName; {make sure it returns the name} 
LoVRefNum := 0; { to determine which volume} 
ioVoliIndex := whichVol; {use this to determine the volume} 
anErr := PBGetVInfo(@volPB, FALSE) ; {do it (FALSE = synchronously) } 
GetIndVolume := anErr; {return error code} 
IF anErr = noErr THEN BEGIN {if no error occurred } 


volRef := ioVRefNum; { return the vol info} 
{other information is available from this record; see the File} 
{Manager's description of PBGetVInfo for more details... } 
END; {if no error} 
END; {with} 
END ; 


To find out about all volumes on-line, you can call this routine several times, starting at 
whichVol := 1 and incrementing whichVol until the routine returns nsvErr. 


Once you have the volume reference number, the same indexing technique can be 
used to find out about each file on that volume, using the low-level File Manager 
routine PBGetFinfo (see the File Manager for more details). 
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#25: Don’t Depend on Register AS Within Trap Patches 
Written by: Bryan Stearns June 25, 1986 





Future software may allow desk accessories to have their own globals by 
changing register a5 when the accessory is entered and exited. This can 
cause problems for applications that patch traps without following certain 
rules. 





If your application patches any traps, it’s important that the patches not depend on 
register AS. This is because you may have intercepted a trap used by a desk accessory. 


if you need access to your globals within your patch, you can save A5 (on the stack, 
perhaps), load as from the low-memory global Currentas (this is guaranteed to be 
correct for your application), do whatever you have to do within your patch, then restore 
a5 on the way out. Note that if you make any traps within your patch (or call the “real” 
version of the routine you patched), you should restore the caller's a5 before doing so. 


There are several ways of depending on a5 within a patch that you should watch out for: 


+ Are you making any references to your global variables, or those of any units 
that you’re using, such as thePort from QuickDraw? These are accessed 
with A5-relative references with negative offsets. | 

e Are you making any inter-segment subroutine calls? These are accessed 
with A5-relative references with positive offsets. 

e Are you using any system calls (either traps or “glue” routines) which will 
depend on a5 during their execution? In this case, you need to be sure that 
you restore the caller’s A5 before executing the call. 


To be safest, patched traps should follow the same rules as interrupt handlers. 





Note: In general, applications should not have to patch any traps, and risk 
compatibility problems if they do! If you’d like help in removing your dependence on 
patching, please contact Macintosh Developer Technical Support at the following 
address: 


Macintosh Developer Technical Support 
Attn: Trap Patches 

Apple Computer, Inc. 

20525 Mariani Ave. MS 27-T 

Cupertino, CA 95014 
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#26: Character vs. String Operations in QuickDraw 


See also: QuickDraw: A Programmer's Guide 
Font Manager: A Programmer's Guide 


Written by: Bryan Stearns 26-Apr-85 





When measuring and drawing strings of text characters, QuickDraw uses fixed-point 
math. This results in rounding error when drawing or measuring scaled characters 
using successive calls to DrawString or DrawChar, as compared with single calls to 
StringWidth or CharWidth. The problem does not occur when using non-scaled fonts. 


The following Macintosh Pascal program demonstrates this problem. It assumes that 
the current System file does not contain a real version of the system font in 11 point, 
but must instead scale the 12-point version. 


program WidthDemo; 
uses 
quickdrawl, quickdraw2; 


const 
thisSize = 11; {try this font size} 


var 
i, j : integer; 
oldPt, newPt : Point; 
s s SEY Z255> 


begin {main} 
TextFont (0); {use the System Font} 
TextSize (thisSize) ; 
s := 'Test String'; 


{Check the difference between StringWidth} 
{and CharWidth} 

writeln('StringWidth:', StringWidth(s)); 
J 20s 

for i := 1 to length(s) do 

begin 

j := j + CharWidth(s[i]); 
end; 
writeln('CharWidth:', j); 


{draw and measure using DrawString} 
moveTo(20, 20); 
GetPen (oldPt); 
DrawString(s); 
GetPen (newPt) ; 
writeln('DrawString:', newPt.h - oldPt.h); 
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{now draw and measure using successive DrawChar calls} 


moveTo(20, 40); 
GetPen (oldPt}); 


for i := 1 to length(s) do 


DrawChar(s[i]); 
GetPen (newPt) ; 


writeln('DrawChar:', newPt.h ~ oldPt.h); 


end. 


StringWidth: 65 
CharWidth: 69 
DrawString: 65 
DrawChar: 69 


StringWidth: 70 
CharWidth: 70 
DrawString: 70 
DrawChar: 70 
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This program's output (in the Text window) wiil look like this: 


lf thisFont Is set to 12 (the system font is normally 12-point) , the result will be: 


Note that the measuring method always matches the drawing method; if you use 
successive CharWidth calis to measure, followed by calls to DrawChar to draw, the 
actual width of the string will match the calculated width. 


Character vs. Strings in QuickDraw 





Macintosh Technical Notes $ 


#28: Finders and Foreign Drives 
See also: Technical Note #15: Finder 4.1 


Written by: Ginger Jernigan May 7, 1984 





This technical note describes the differences in the way the 1.1g, 4.1 and 5.0 
Finders communicate with foreign (non-Sony) disk drives. 





identification 


Foreign disk drives, meaning non-Sony drives, can send an icon and a descriptive 
string to the Finder. The icon is used on the desktop to represent the drive. The string is 
displayed in the "Get Info” box for any object belonging to that disk. When the Finder 
notices a "non-Sony” drive in the VCB queue, it will issue 1 or 2 control calls to the disk 
driver to get the icon and string. 


Finder 1.1g issues one control call to the driver with CSCode = 20 and the driver returns 
the icon ID in CSParam. This method has problems because the icon ID was tied to a 
particular system file. So, if the Finder switched-launch to a floppy, the foreign disk's 
icon reverts to the Sony's. 


Finders 4.1 and 5.0 issue a "newer" control call and, if that fails, they issue the old 
Control call. The new call has CSCode = 21, and the driver should return a pointer in 
CSParam. The pointer points to a type ICN# followed by a 1..31 byte Pascal string 
containing the descriptor. This implies that the icon and the string must be part of the 
disk driver's code because only the existence of the driver indicates that the disk is 
attached. 


This. has implications about the translation of the driver for overseas markets, but the 
descriptor will usually be a trademarked name which isn't translated. However, the 
driver install program could be made responsible for inserting the translated name into 
the driver. 


Drivers should respond to both contro! calls if compatibility with both Finders is desired. 


However, if you ship the disk out with the 4.1 or 5.0 Finder, responding to just Control 
#21 would be OK. 


Technical Note #28 page 1 of2 Finders and Foreign Drives 


Formatting Foreign Drives 


When the user chooses the Erase option in the Finder, a non-Sony driver needs to 
know that this has happened so it can go off and format the disk. There is a mechanism 
inthe 4.1 and 5.0 Finders that notifies the driver that the drive needs to be formatted and 
verified. They first issue a Control call to the driver with the CSCode = 6. This tells the 
disk driver to go out and format the drive. They then issue a Control call with a CsCode 
= 5 to the driver, which tells the driver to verify the drive and make sure everything is OK. 


Other Nifty Things to Know About 


Finders 4.1 and 5.0 also permits the user to drag any online disk to the trash can. The 
Finder will clean up the disk state, issue an Eject call followed by an Unmount call to the 
disk and then, an event loop later, reclaim all the memory. This means any 
program/accessory used to mount volumes should reconcile its private data, menus, 
-= etc. to the current state of the VCB queue. These Finders also notice if a volume 
disappears and will clean up safely. But, because of a quirk in timing, a mount manager 
cannot unmount one volume then mount another immediately; it must wait for the Finder 
to loop around and clean up the first disk before it notices the second. (It should have 
cleaned up old ones before it notices new ones, but it doesn't.) This should enable all 
hard disks to have a desk accessory mount manager which is a nicer user interface 
anyway. 


As an aside... The 5.0 Finder also allows you to drag the System disk to the trash. In the 


4.1 Finder it just ignored you. In the 5.0 Finder it takes the volume offline as if you had 
chosen the Eject option in the Finder. 
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#29: Resources Contained In The Desktop File 


See also: Putting Together a Macintosh Application 
Structure of a Macintosh Application 
Written by: Ginger Jernigan May 7, 1985 
Modified by: Ginger Jernigan October 16, 1985 
Ginger Jernigan December 2, 1985 





This technical note describes the resources found in the Desktop file. 





The Desktop file contains aimost the same resources for both the old Macintosh File 
System (MFS) and the Hierarchical File System (HFS). This technote describes the 
resources found in both. However, don't plan anything critical on the format of the 
desktop file. It can and probably will change in the future. This information is for reading 
only. This means your application can read it but it should NEVER write out information 
of its own, because the Finder, as well as Macintosh Technical Support, won't like it. 


The Desktop is a resource file which contains the folder information on an MFS volume, 
the Get Info comments, the application bundles, FREFs and ICN#s, and information 
concerning the whereabouts of applications on an HFS disk. Everything except the 
comments are preloaded when the desktop is opened, making it easier for the Finder to 
find things. 


The contents of the Desktop file are described below. The resource types are the same 
for both MFS and HFS volumes unless otherwise stated. 


APPL: This resource type is used by the Hierarchical File System to locate 
applications. This is used by the Finder to locate the right application when a 
document is opened. Each application is identified by the Creator, the Directory 
number, and the Application name. This is used only by HFS. 


BNDL: This resource type contains a copy of ali of the bundies for all of the 
applications that are either on the disk or are the Creators of documents that are on 
the disk. This is used by the Finder to find the right icons for your documents and 
applications. If you have a document whose creator the Finder has not seen yet, it 
will not be in the Desktop file and the default document icon wili be used. 

FREF: This contains a copy of all of the FREFs referenced in the bundles. 


FCMT: This resource contains all of the Get Info comments for your applications and 
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documents. On MFS volumes the ID is a hash of the object's name. The hashing 
algorithm is as follows: 


; HashString( str: STR255 ): INTEGER; 


: The ID for the FCMT returned in function result 


MOVE.L (SP)+,A0 ; get RTS 
MOVE.L (SP)+,Al ; get string ptr 
MOVEQ #0,D0 ; get string length 
MOVE.B (A1)+,DO 
MOVEQ #0,D2 ; accumulate ID here 
GO 
MOVE.B (A1)+,D1 ; get next char 
EOR.B D1,D2 ; XOR in 
ROR #1,D2 ; stir things up 
BMI.S @1 ; ID must be negative 
NEG D2 
Q1 
SUBQ #1,D0 
BNE @0 
MOVE D2, (SP) 
JMP (A0) 


For HFS volumes, the ID of the resource is randomly generated using UniquelD. This 
ID is in turn kept in the Finder file information record in a new field called 
FFComment. ($5E). 


FOBJ: This resource type contains all of the folder information for an MFS volume. 
The format of this resource is not available. You shouldn't play with them. This is only 
in an MFS volume’s Desktop file. 


ICN#: This resource type contains a copy of all of the ICN# resources referenced in 
the bundles and any others that may be present. 


STR: This is a string that identifies the version of the Finder, but it isn't necessarily 
correct (meaning sometimes it isn't right). 


Creators: The Creators for each application listed in the bundle is in the Desktop file 
for reference purposes only. The associated data is set to nil. 


- Be aware that if a resource is copied from an application resource file and there is an ID 
conflict, the Finder will renumber the resource in the Desktop file. 
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#30: FONT Height Tables 
See Also: The Font Manager 


Written by: Gene Pope April 25, 1986 





This Technical Note describes how the new Font Manager calculates height 
tables for fonts and how you can force recalculation if necessary. 


i a 


in order to expedite the processing of FONTs, the Font Manager in the 128K ROMs 
calculates a height table for all of the characters in a FONT when the FONT is first 
loaded into memory. This height table is then appended to the end of the FONT 
resource in memory; if some program (such as a FONT editor) subsequently saves the 
FONT, the height table will be saved with the FONT and will not have to be rebuilt again. 
This is fine for most cases except, for example, when the tables really should be 
recalculated, such as in a FONT editor when the ascent and/or descent have changed. 


The following code segment is an example how to eliminate the height table from a 
FONT: | 


If (BitAnd(hStrike*%*. format, $1)=1) 
Then Begin {We have a height table} 
{Truncate the height table} 
SetHandleSize (handle (hStrike) ,GetHandleSize (Handle (nStrike) - 
(2* (hStrike**.lastChar-hStrike**.FirstChar) +3))); 


{We no longer have a height table so set the flag to indicate that} 
hStrike**.format := BitAnd(hStrike**.format, SFFFFFFFE) ; 
End; 


where hStrike is a handle to the FONT resource (handle to a FontRec). 


After the height table has been eliminated, the modified FONT should be saved to disk 
(with ChangedResource/WriteResource) and purged from memory (using 
ReleaseResource). This is an important step, because the Font Manager does not 
expect other code to go behind its back removing height tables that it has so carefully 
calculated. Purging and reloading the FONT will cause the Font Manager to recaiculate 
the height table since it no longer has one. 
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#32: Reserved Resource Types 


See also: 


Written by: 


Resource Manager: A Programmer's Guide 


Scott Knaster 


5/13/85 





Your applications and desk accessories can create their own resource types. To avoid 
using type names which have been or will be used the system, Apple has reserved all 
resource type names which consist entirely of lower-case ASCII characters ($61 
through $7A) and "international" characters (greater than $7F). 


In addition, Apple has reserved the following resource types which contain upper-case 
characters and the # character: 


ALRT 
DITL 
FOBJ 
ICON 
MENU 
PAT# 
STR# 


BNDL 
DLOG 
FONT 
INIT 
MINI 
PDEF 
WDEF 


CDEF 
DRVR 
FREF 
INTL 

NBPC 
PICT 

WIND 


CNTL 
DSAT 
FRSV 
MACS 
PACK 
PREC 


CODE 
FCMT 
FWID 

MBAR 
PAPA 
SERD 


CURS 
FKEY 
ICN# 
MDEF 
PAT 
STR 


Note that most of these have been around for some time and should be familiar to you 
already. This doesn't mean, of course, that you can't create your own resources of 
these types; obviously, you will have your own CODE, MENU, WIND, and so on. This 
list provides names which you should not use for new, custom resource types. 
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#33: ImageWriter II Paper Motion 
Written by: Ginger Jernigan April 30, 1986 





The purpose of this Technical Note is to answer the many questions asked 
about why the paper moves the way it does on the ImageWriter II. 





Many people have asked why the paper is rolled backward at the beginning of a 
Macintosh print job on the ImageWriter Il. First, note that this only happens with pin-feed 
paper (i.e. not with hand-feed or the sheet-feeder) and only at the beginning of a job. 


it is not a bug, and it is not malicious programming. It is simply that users are told in the 
manual to load pin-feed paper with the top edge at the pinch-rollers, making it easy to 
rip off the printed page(s) without wrecking the paper that is still in the printer or having 
to roll the paper up and down manually. At the end of every job, the software makes 
sure that the paper is left in this position, leaving the print-head roughly an inch from the 
edge. If something is to be printed higher than that, the paper has to be rolled 
backwards. | 


As you are probably aware, the “printable rectangle” (rPage) reported to the application 
by the print code begins 1/2 inch from the top edge, not one inch. The reason for that is 
that we want a document to print exactly the same way whether you are printing on the 
ImageWriter | or Il. On the ImageWriter I, the paper starts with the print-head 1/2 inch 
from the top edge, so the top of rPage is at that position for both printers. 


There is no way to eliminate the reverse-feed action, because the user would have to 
load the paper a different way AND the software would have to know that this was done. 


Incidentally, in addition to the paper motion described above, there is also the “burp.” 
This is a 1/8-inch motion back and forth to take up the slop in the printer’s gear-train. It 
is needed on the old-model printer, and there is debate about whether or not it’s 
needed on ALL ImageWriter Il’s, or only some, or none. The burp has been in and out 
of the ImageWriter II code in various releases; right now it’s in. 
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#34: Userltems in Dialog Boxes 
See also: Dialog Manager Programmer's Guide 


Written by: Bryan Stearns 29 May 1985 





The Dialog Manager doesn't go into detail about how to manage userliems 
in dialog boxes. This Technote describes the process. 


i Uģa 


"How do | use userltems?” There are three parts to the answer to this question: you 
must define the dialog box, load the box and install our userltem, and respond to 
events related to the userltem. Let's tackle these in order: 


Defining a dialog box with a useritem. 


You should define the dialog box in your resource file as follows. Note that it is defined 
as Invisible: this is because we have to play with the userltem before it can be drawn. 


Type DLOG 
, 1001 Resource iD for this box 
100, 100,300,400 Rectangle for the window 
Invisible 0 NoGoAway 0 Note NOT visibie! 
1001 Item list ID 
Test Window Title 
Type DITL | 
, 1001 Matching item list 
2 number of items 
Btnitem Enabled an OK button 
160 190 180 280 rect for button 
OK Button title 
UseriItem Enabled a user item! 
10 10 32 32 | boundsrect for user item 
in r rin n ial 


Before we can actually show the dialog box to the user, we need two support routines. 
The first procedure is called by the Dialog Manager whenever our userltem needs to 
be drawn. It is installed (as shown below) after GetNewDialog but before 
ShowWindow. All it does is draw the user item. A simple draw procedure might be as 
foliows: | 
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PROCEDURE myDraw(theDialog: DialogPtr; theItem: INTEGER); 


VAR iType: INTEGER; {returned item type} 
iBox: Rect; {returned boundsrect } 
iHdl: Handle; {returned item handle} 

BEGIN | 

GetDItem(theDialog, theItem, iType, iHdl, iBox); {get the box} 
FillRect (iBox, 1tGray) ; {fill with light gray} 
FrameRect (iBox); {frame it} 


END; {myDraw} 


The other necessary procedure is a filter procedure, called by the Dialog Manager 
whenever ModalDialog receives an event (note that this only applies when calling 
ModalDialog; see below for modeless dialogs). The default filterproc checks to see if 
the user has typed the return or enter keys; if so, it simulates pressing of the OK button 
(or whatever item 1 is). To support userltems, the filterproc must handle events for any 
userltems in the box, in addition to performing the default filterproc tasks. This short 
filterproc does this; when the user clicks in the useritem, it inverts it: 


PROCEDURE myFilter(theDialog: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER) : BOOLEAN; 


VAR kPtr: “SignedByte; {for enter/return} 
iType: INTEGER; | {returned item type} 
iBox: Rect; {returned boundsrect} 
iHdl: Handle; {returned item handle} 
mouseLoc: Point; {we'll play w/ mouse} 

BEGIN | 

MyFilter := FALSE; {assume not our event} 
CASE theEvent.what OF {which event?} 
keyDown, autoKey: BEGIN {he hit a key} 
kPtr := POINTER (ORD4 (theEvent.message)+3); {get keycode} 
IF kPtr^ IN [13,3] THEN BEGIN {he hit CR or Enter} 
MyFilter := TRUE; {we handled it} 
itemHit := 1; {he hit the lst item} 


END; {he hit CR or enter} 
END; {keydown} 


mouseDown: BEGIN {he clicked} 
mouseLoc := theEvent.where; {get the mouse pos'n} 
GlobalToLocal {mouseLoc) ; {convert to local} 


GetDItem(theDialog, 2,iType,iHdl,iBox); {get our box} 
IF PtInRect (mouseLoc, iBox) THEN BEGIN {he hit our item} 
InvertRect (iBox); 
END; {if he hit our userItem} 
END; {mousedown } 


END; {event case} 
END; {myFilter} 
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invoking th 


When we need this dialog box, we load it into memory as follows: 


PROCEDURE DoOurDialog; 


VAR theDialog: DialogPtr; {the dialog pointer} 
LType: INTEGER; {returned item type} 
iBox: Rect; {returned boundsrect} 
iHdl: Handle; {returned item handle} 

BEGIN 


myDialog := GetNewDialog(1001,NIL,POINTER(-1)); {get the box} 
GetDItem(myDialog,2,iType, iHdl, iBox); {2 is the item number} 
SetDItem(myDialog,2,iType, @myDraw,iBox); {install draw proc} 


ShowWindow (myDialog); {make it visible} 
REPEAT 

ModalDialog (@MyFilter,whichItem) ; {let dialogmgr run it} 
UNTIL whichItem = 1; {until he hits OK.} 
DisposDialog (myDialog) ; {throw it away} 


END; {DoOurDialog} 


in ritems with m | ial 


if you're using userltems in a modeless dialog box, the draw procedure will get called 
when DialogSelect receives an updateEvent for the dialog box. When the user presses 
the mouse button on your useritem, DialogSelect will return TRUE and itemHit equal to 
the item number of the userltem. Your code can then handle this just like the 
mouseDown case in the example above. 
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#35: QuickDraw DrawPicture Problem 


See also: QuickDraw 
Technical Note #21—Quickdraw’s Internal Picture 
' Definition 
Written by: Mark Baumwell | June 19, 1986 





When recording a QuickDraw picture that references (draws) another picture `>xt 
recorded (i.e with DrawString) after the other picture is referenced isn’t s. J 
correctly when the picture is drawn. The problem lies with the txRatio opcode wnile 
the picture is being recorded. Unfortunately, the only way to work around the bug is to 
record the picture and then post-process it, replacing all txRatio opcodes ($10) with 
null opcodes ($00). 
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#36: Drive Queue Elements 


See also: File Manager Programmer's Guide 
Device Manager Programmer's Guide 


Written by: Bryan Stearns June 12, 1985 


This note expands on Inside Macintosh's definition of the drive queue, 
which is given on page 62 of the File Manager Programmer's Guide. It also 
documents AddDrive, a useful routine that adds drives to the drive queue. 


As shown in Inside Macintosh, a drive queue element has the following structure: 


TYPE DrvQEl = RECORD 


{ flags: LongInt; } 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {not used} l 
doprive: INTEGER; {drive number} 
dORefNum: INTEGER; {driver reference number} 
dQFSID: INTEGER; {file-system identifier} 
doDrvSize: INTEGER; {optional: number of blocks} 
END; 


Although the doprvSize field is listed as optional, it must be filled in for devices other 
than standard 3 1/2 inch drives. The Disk Initialization Package uses this field to create 
the proper directory and block map when initializing a volume on the drive. 


Also, the flags field is presented in Pascal comment-brackets. How is this field 
accessed? The flags field begins 4 bytes before the address pointed to by the 
DrvQEIPtr. In assembly language, accessing this isn't a problem: 


MOVE.L -4({AQ),DO ;A0 = DrvQEl1Ptr; get the flags 


If you're using Pascal, it’s a little more complicated. You can get to the flags with this 
routine: 


FUNCTION DriveFlags (aDQEPtr: DrvQE1Ptr): LongInt; 
VAR FlagsPtr: “Longint; {we'll point at the flags with this} 
BEGIN 
{subtract 4 from the DrvQE1Ptr, and get the LongInt there} 
FlagsPtr := POINTER (ORD4 (aDQEPtr) -4); 
DriveFlags := FlagsPtr%; 
END; 
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Creating New Drives 


To add a drive to the drive queue, assembly-language programmers can use the 
function defined below. It takes two parameters: the driver reference number of the 
driver which is to "own" this drive, and the size of the new drive in blocks. It returns the 
drive number created. It is vital that you not hard-code the drive number; if the user 
has installed other non-standard drives in the queue, the drive number you're 
expecting may already be taken. (Note that the example function below arbitrates to 
find an unused drive number, taking care of this problem for you. Also, note that this 
function doesn't mount the new volume; your code should take care of that, calling the 
Disk Initialization Package to reformat the volume if necessary). 


a an es ee es eG SD A YA SS SP SND ND SE ED Re AA oe am am mb et es es es es a a eee ee S eee —_— =: 


;Add a drive to the drive queue. Returns the new drive number, or a negative 
serror code (from trying to allocate the memory for the queue element). 
:FUNCTION AddADrive (drvSize,drvrRef:INTEGER) : INTEGER; 


bd es cer cee ee cee ce ta we A A <A SS SS Sh SS SAD SS YD SD SEEN SEEDED ED EP en ED HED me Ss SED ENR TSS —_ 


sStack frame: 


ADResult .EQU 12 ;result. 

ADArgs .EQU 4 ;four bytes of parameters 

ADSize . EQU 10 ;parm: drive size 

ADDrvrRef .EQU 8 ;parm: driver Refnum 

ADRetAddr .EQU 4 return address 

ADIOQEL -EQU -i10QE1Size :IO Queue Element for call to MountVol 
AddADrive LINK A6, #ADIOQEL ¿create stack frame 


MOVEM.L D3-D4/A2-A3,-(SP) ;save regs 


: Search the existing drive queue for an unused number 
LEA DrvQHdr,A2 ;get the drive queue header ptr > 
MOVE.L qTail(A2),A3 ;get queue tail ptr 

MOVE.L qHead(A2),Al ;get head ptr 


MOVEQ #4,D0 ¿start looking at drive 4. 

@2 CMP .W dqDrive(Al),DO ;does this drive already have our number? 
BEQ.S @3 ; yep, bump the number and try again. 
CMP .L A1,A3 > no, are we at the end of the queue? 
BEQ.S @4 ; if yes, our number‘s unique! Go use it. 
MOVE.L qLink({Al),Al ;point to next queue element 
BRA.S @2 ;go check it. 


:This number is taken. Pick another and start over. 


@3 MOVE.L qHead(A2),Al ;start at the top of the list again. 
ADDO #1,D0 ;bump to the next number 
BRA.S @2 try next number. 


;We got a good number (in DO.W). For now, set if aside. 
aå MOVE.W D0, ADResult (A6) ;return it to the user. 
MOVE.W D0,D3 ssave it here,too. 
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:Get room for the new DQE - we use a constant here because the Sysequ constant 
doesn't take into account the flags longint AHEAD of the QEIPtr, or the Size 


;word at the end. 


MOVE #18,D0 size of drive queue element, adjusted 
_NewPtr, SYS iget the memory for it. 
BEQ.S @5 sno error... continue. 
MOVE .W DO,ADResult (A6) ;couldn't get the memory! Return error 
' BRA.S @1 ; and exit. 
:Fill out the- DQE and call AddDrive 
@5 MOVE.L #$80000, (A0)+ ;flags: non-ejectable; bump ptr past flags 
MOVE.W #0,DQFSID(A0) ;'local file system' 
MOVE.W ADSize (A6),DQDrvSize(A0) ;blocks on this drive 
MOVE.W D3,D0 ;get the drive number back, into DO hi word 
SWAP DO zmove it to DO hi word 
MOVE .W ADDrvrRef (A6} ,DO0 smove the drvr number into DO lo word 
_AddDrive ;add this drive to the drive queue. 
@1 MOVEM. L (SP}+,D3-D4/A2-A3 ;restore regs 
UNLK A6 ;drop frame 
MOVE.L (SP)+,A0 ;get rtn addr 
ADDQ #ADargs, SP ¿strip args 
JMP (A0) back to caller 


- End - 
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#37: Differentiating Between Logic Boards 


see also: The Macintosh Hardware 
The Macintosh Hardware (Beta draft) 


Written by: Mark Baumwell | June 19, 1986 





This Technical Note explains how to determine whether you are running on a 
Macintosh Plus logic board or a Macintosh 128/512K logic board. This may 
be useful, for instance, if you wanted to programmatically use the output 
handshake line on a Macintosh Plus logic board. | 





To tell if you are running on a Macintosh Plus board instead of a 128/512K board, check 
the low-memory global HWCfgF lags (a word at location $822). The bits inthe word are 
defined as follows: 


Bit 15 = 1 if and only if SCSI is present. 

Bit 14 = 1 if and only if the new clock chip is present. 

Bit 13 = 1 if and only if Bit 14 = 1 and the “extra” parameter RAM bytes are valid. 
Bits 12-0 are reserved for future use; they are currently 0. 


You should check bit 15 of this word; if it is a 1 then a Macintosh Plus logic board is 
present, otherwise a 128/512K board is present. This is the technique that the 128K 
ROM uses to distinguish Macintosh Plus logic boards. 


As a point of interest, there are 17 address lines to the ROMs on a 128/512K board, and 
18 lines to the ROMs on a Macintosh Plus board. Therefore, on a 128/512K board, 
addresses wrap starting at address $420000 (and at $20000 byte boundaries 
thereafter), and the contents of address $400000 are equal to those of $420000. Ona 
Macintosh Plus logic board, addresses wrap at $40000 byte boundaries, so the 
contents of address $400000 would NOT be equal to those of $420000. 
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#38: The Macintosh Plus ROM Debugger 
Written by: Louella Pizzuti June 20, 1986 


The debugger in ROM on the Macintosh Plus Is very limited. It recognizes the following 
commands: 
PC [expr] (program counter) 


Typing Pc on a line by itself displays the program counter. Typing Pc 50000 sets the 
program counter to $50000. 


SM [address [number(s)]] (set memory) 

Typing SM on a line by itself displays the next 96 bytes of memory. Typing sm 50000 
will display memory starting at $50000. Typing SM 50000 4849 2054 6865 7265 
2120 will set memory starting at $50000 to $4849... Subsequently hitting return will 
increment the display a screen at a time. : 

DM [address] (display memory) 

Typing DM on a line by itself displays the next 96 bytes of memory. Typing DM 50000 
will display memory at $50000. Subsequently hitting return will increment the display a 
screen at a time. 

SR [expr] (status register) 


Typing SR on a line by itself displays the status register. Typing SR 2004 sets the status 
register to $2004. 


TD (total display) 

Displays memory at the “magic” location $3FFC80, which contains the current values of 
the 68000’s registers. The registers are displayed in the following order: DO-D7, 
AO-A7, PC, SR. 


G [address] (go) 


Executes instructions starting at address. if G is typed on a line by itself, execution 
begins at the address indicated by the program counter. 


Note: If you want to exit to the shell, you just need to type: SM 0O A9F4,thenG 0 
Note: if you crash into the debugger and the system hangs, try turning off your modem. 
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#39: Segment Loader Patch 


See also: The Segment Loader 
Technical Note #57—Macintosh Plus Overview 
Technical Note #64—IAZNotify Pointer 


Written by: Russ Daniels & Bryan Stearns August 1, 1985 
Modified by: Jim Friedlander July 11, 1986 


The Segment Loader in the 64K ROM can cause segments to becc*: 
locked down in the middle of memory, fragmenting the application heap. © 
This patch fixes that problem. 


The Segment Loader problem occurs when the following sequence of events take 
place: 


e A segment (other than the “blank” segment) is unloaded, with a call to 
UnloadSeg. This causes the segment to be unlocked and purgeable, but does 
not kick it out of memory. 


e A memory request (such as NewPtr) causes the unloaded segment to be 
moved up in memory. 


¢ The segment is needed again. The Segment Loader routine LoadSeg notices 
that although the segment was unloaded, the actual code is still around. So it 
locks it down (in place!) and invokes the called routine in that segment. 


This can cause the heap to become fragmented. If you feel that moving code segments 
high will heip your application’s memory management, you can use this patch which 
causes an unlocked segment to be moved to the top of the application heap when 
LoadSeg is called. Please note that the 128K ROM Segment Loader automatically 
moves unlocked CODE resources to the top of the application heap. This patch 
depends on your calling MaxApplZone before any unlocked segments are loaded (or 
even worse fragmentation can occur). 


This patch normally requires that each segment be unlocked (other than segments 0 
and 1; the jump table [CODE 0] and the main segment [CODE 1] are never 
UnloadSeg'd). You will have to clear the “locked” bit in the resource attributes of each 
of your CODE resources (other than 0 and 1), so that the Resource Manager won't call 
ReserveMem before loading the segment. This can be a tedious task if your application 
has more than a few segments, so an Unlock call can be conditionally assembled 
into the patch; if the Unlock call is included, your application's memory usage may 
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change, but you won't have to worry about unlocking the attributes of your CODE 
resources for each build. Before you ship your application, you should remove the 

_Unlock cail and unlock all CODE resources that you want to move high in the heap 
(this does not include CODE 0 and CODE 1). A small utility program that unlocks all 
CODE resources except CODE 0 and CODE 1 is available from Tech Support. 


This patch should be made by any application which calls UnloadSeg. The patch must 
be copied into your program’s source verbatim (except for changes necessary to 
accommodate your particular assembler—this is in Lisa Workshop Assembler form), 
and placed in the main segment. You must link with Obj /OSTraps.obj (for access to 
MoveHHi, the routine which moves the code resource into the high end of the 
application heap). 


A call to the FixLS routine should be made once at application start-up time, just after 
a call to MaxApplZone (used to expand the application heap to its largest size), but 
(ideally) before any calls have been made into alternate segments. Just before your 
application exits, a call should be made to UnFixLS to remove the patch. If you are 
using an IAZNotify routine, a call to UnFixLS should go in that routine. 


. INCLUDE -#12-tlasm/equates.sym ;all the normal equ’s 
. PROC Fixer 

.REF MoveHHi sin Obj/OSTraps.0bj 

. DEF FixLS, UnFixLS 


;set the following .EQU to 0 for shipping code or if CODEs are unlocked 


InclUnlk .EQU od ;l1 if yes, Q0 if no. 

; Install the patch 

FixLS ;Future ROMs make this patch unnecessary; 
;check to see if we’re running on them. 
TSI- B ROM85 ;if future, the hi bit’s set 
BPL.S FixkRTS ;yes, do nothing. 


; get old trap address so we can save it 

MOVE.L #$A9F0,DO0 

_GetTrapAddress 

MOVE.L A0O,-(SP) ;save old address on the stack 
7All trap addresses in RAM must point into the 

;system heap. Get a little block there to 

;pass control to a routine of ours 


MOVEQ #10,D0 ;Room for a JMP Abs.L(6 bytes) and 
zold trap address(4 Bytes) 
_NewPtr, SYS ;put in **System** heap 
BNE.S FixErr ;oops! couldn’t get the RAM! 
MOVE.W #S4EF9, (AQ) ; JMP Abs.L instruction 
LEA myPatch, Al ;get the patch address 
MOVE.L à1,2 (A0) ;put the address in 
MOVE.L {(SP)+, 6 (AQ) ;put old address in our heap block 
¿Now point the patch at our little vector (in A0) 
MOVE.W #SA9F0,D0 ;a LoadSeg trap 
© _SetTrapAddress : 
FixRTS RTS ;And we’re done installing! 
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;Remove the patch 


UnFixLS TST.L ROM85 ;did we patch it? ` 
BPL.S UnRTS jno, do nothing. 
MOVE.W #$A9F0, DO ;get our patch address 
_GetTrapAddress 
MOVE.L 6(A0),~(SP) ;get old trap address, put on stack 
_DisposPtr ;throw away our block in system heap 
MOVE.L (SP}+,A0 ;un-patch 
MOVE .W #$A9F0, DO 
_SetTrapAddress ;reset it back to normal 

FixErr ;error checking here?? But, as the 


;saying goes, if you can’t get 10 
¿bytes in the system heap you’ve got 
real trouble. 
MOVE.L (SP) +,A0 ;clean up the stack before exiting 
UnRTS RTS 


;This is the patch itself. 


MyPatch SUBQ.L #4,SP ;make room for handle 
MOVE.L #'CODE',~(SP} 
MOVE.W 12 (A7),-(SP) ;copy the segment number 


_GetResource ;get the handle 


IF InclUn1k 

MOVE.L (SP) ,A0 ; leave handle on stack 

_HUnLock ;get ready to move it. 

. ENDC 

JSR. MoveHHi smovitup! (hdl on stack) 

MOVE.L #SA9F0,D0 ;get the trap address 
_GetTrapAddress 

MOVE.L 6 (A0), A0 ;get old address 

JMP (A0) ;pass the call to original LoadSeg 
. END 
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#40: Finder Flags 


See also: 


Written by: 


The File Manager 
Jim Friedlander June 16, 1986 


The Finder keeps and uses a series of file information flags for each file. These flags 
are located in the FdFlags field (a word at offset $28 into an HParamBlockRec) of the 
ioFLFndriInfo record of a parameter block. These flags may change with newer 
versions of the Finder. Finder 5.3 assigns the following meaning to these flags: 


Bit 
0 


Oona RGN = 
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Meaning 

Set if file/folder is on the desktop (Finder 5.0 and later) 
bFOwnAppl (used internally) 

reserved, currently unused 

reserved, currently unused 

bFNever (never SwitchLaunch) (not implemented) 
bFAlways (always SwitchLaunch) 

Set if file should be cached (not implemented) 

Set if application is shared and is opened read-only (128K ROM only) 
Inited (seen by Finder) 

Changed (used internally by Finder) 

Busy (copied from File System busy bit) 

NoCopy (not used in 5.0 and later, formerly called BOZO) 
System (set if System file) 

HasBundle 

Invisible 

Locked 
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#41: Drawing Into an Offscreen Bitmap 


See also: QuickDraw: A Programmer's Guide 
Written by: Jim Friedlander July 1, 1985 
Ginger Jernigan 
Modified by: Jim Friedlander September 5, 1985 
Modified by: Jim Friedlander November 26, 1985 





Here is a short example of drawing to, then copying from, an offscreen 
bitmap. 





The following is a short example of drawing to, then copying from, an offscreen bitmap. 
The only major concern when setting this up is that the number of rowbytes in the 
bitmap is even. Given these constants and variables: 


CONST 
OffLeft = 30; 
OffTop = 30; 
OffBottom = 250; 
OffRight = 400; 

VAR | 
OffScreen : BitMap; {Our offscreen bitmap} 
OldBits : BitMap; {We need to save our old bitmap//portBits} 
SizeOfOfE : Size; {Size of our offscreen Bitmap} 

 OffRowBytes: Integer; {# of RowBytes in our offscreen bitmap} 

MyWindow : WindowPtr; {a windowPtr for use with NewWindow} 
MyString = StrZ2so: 


the new bitmap can be allocated with the following statements: 


If OffRight-OffLeft <= 0 then {bad case} 
OffRowBytes:= 0 
else 
OffRowBytes:= (((OffRight - OffLeft -1) div 16) +1) * 2; 


{Number of bytes in our bitmap= RowBytes*Number of Rows} 
SizeOfOff:= (OffBottom-OffTop) * OffRowBytes; 
offSetRect (bRect, -OffLeft, -OffTop) ; {Adjust for local coordinates} 


With OffScreen do Begin 
{Allocate space on the heap and point baseAddr to it} 
baseAddr:= QDPtr(NewPtr(SizeOfOff) ); 
rowbytes:= OffRowBytes; {Number of RowBytes} 
bounds:= bRect; {BoundsRect } 
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End; {With} 


We are now ready to draw into our offscreen bitmap: 


OldBits:= MyWindow*’.PortBits; {Save old bitmap} 
SetPortBits (OffScreen) ; {draw to new bitmap} 


{Since it's just an area of memory, we'd better clear it before we start} 
FillRect (MyWindow~’.PortRect, white) ; 


{Example drawing} 

SetRect (OvalRect, 30,30,190,150); {Do our drawing stuff} 

FilldOval (OvalRect, Black); 

InsetRect (OvalRect,1,20); 

FillOval (OvalRect, white); 

InsetRect (OvalRect, 40,1); 

FilloOval (OvalRect, Black) ; 

MyString:= ‘The EYE'; 

MoveTo (30+ (80—-(StringWidth (MyString) div 2)),180); 

DrawText (@MyString,1, length (MyString) ); 

SetPortBits (OldBits) ; {Switch back to our 
on-screen portBits} 


Now we're ready to do the CopyBits, copying the image that we've drawn in the 
offscreen bitmap to MyWindow‘.PortBits, from OffScreen’s boundsrect to 
MyWindow’.PortRect: 


. CopyBits (OffScreen, MyWindow*.PortBits, OffScreen.bounds, 
MyWindow’ .PortRect, srcCopy,NIL); 


Notice here that if MyWindow’.PortRect and OffScreen.bounds are not the same size, 
CopyBits will scale the bit image that is being copied. 


Please note that this way of doing things is NOT faster than simply defining a picture 
and then drawing it to your window. There are cases, however, such as text rotation, 
where it will be advantageous to do the drawing off the screen, manipulate the bit image 
and then copy the result to the visible window. 
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#42: Pascal Routines Passed by Pointer 
See also: Macintosh Memory Management: An introduction 


Written by: Scott Knaster July 22, 1985 





Pascal routines passed by pointer are used in many places in conjunction with 
Macintosh system routines. For example, filter procedures for modal dialogs are 
passed by pointer, as are controls' action procedures (when calling TrackControl), a: a. 
VO completion routines. 


lf you're using Lisa Pascal, the syntax is usually 
partCode := TrackControl (theControl, startPt, @myProc) 


where myProc is the procedure passed by pointer (using the @ symbol). 


Because of the way that Lisa Pascal (and some other compilers) construct stack 
frames, any procedure or function passed by pointer must not have its declaration 
nested within another procedure or function. If its declaration is nested, the program 
will crash, probably with an illegal instruction error. The following example 
demonstrates this: 


program CertainDeath; 


procedure caliDialog; 
var x : integer; 


procedure myFilter (theDialog : DialogPtr; var theEvent 
EventRecord; var itemHit : integer) : Boolean; 
{ note myFilter's declaration is nested within callDialog } 
begin 
{ body of myFilter } 
end; { of myFilter } 


begin { procedure callDialog } | 
ModalDialog (@myFilter, itemHit) {<---~ will crash here} 


{ more statements in callDialog } 
end; 


begin { main program } 
callDialog; 
end; 
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#43: Calling LoadSeg 
See also: Segment Loader Programmer's Guide 


Written by: Gene Pope 10/15/85 


LoadSeg does not return the same way that other traps do. For this reason, 
it must be called from assembly language. 


Inside Mac briefly mentions LoadSeg as a call that you would normally never need to 
call. For those rare times when it is needed, it is important to realize that LoadSeg is not 
called in the normal manner. Due to the different way in which LoadSeg returns, it must 
be called from assembly language. 


eo ee) cee es eee ee ee ee es ee ee ee ee ee ee ee ee ees eee eee ee ee eee eee eee eo oe ee cee es ces ce es ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee ee ee ees ee ee eee ee ee ee ee ee 


JTEntry MOVE.W #n,-(SP); Push segment number n onto stack 
_LoadSeg ; (SA9FO) Call to LoadSeg 
Figure 1 


The jump table entry for a code segment that is not loaded. 


-e n ee ee ce es gis ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ees eee ee ee ei ee ee es eee ee ee ee ee ee ee ee ee ee ee 


JTEntry JMP RoutineAddress ; Call the routine (address 
; derived from adding routine offset into the segment to the 
; actual address the segment was loaded at). 


‘Figure 2 
The jump table entry for a code segment that is loaded. 


When LoadSeg is called, it will have been called by a code segment like the one in 
figure 1. After loading the CODE resource that has the ID number called for, LoadSeg 
will patch the jump table with JMP instructions as in figure 2. As long as the segment is 
loaded, a call through the jump table to access the routine will jump to the appropriate 
routine address. 


The way LoadSeg jumps to the routine after loading the segment and patching the jump 
table is by taking the return address it was called with, subtracting 6 from it, and using it 
as the new return address. This will cause execution to resume at the JMP instruction 
that was just patched in the jump table. 


lf you are calling LoadSeg directly, you must take into account the different way in which 
LoadSeg returns. An example of this is shown in figure 3. 
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es BRA.S callLoadseg 
BRA.S afterLoadSeg 


NOP 


callLoadSeg 
_Loadseg 
afterLoadSeg 


; Jump around the stuff below. 

; Instruction that LoadSeg will 
; return to. 

; To put the previous instuction 
; in the right place. 
f 

f 

f 

f 


; Make the call to LoadSeg. 


Continue on with the program. 


= oe oe oe ee ee ee ee ee ee ee ee ee a ee ee ee A ee ss ee ee ee ee ee ee ee ee eee 


Figure 3 


Cailing LoadSeg. 


The following example is a code segment from a program (Resource Editor) that 
needed to modify the functionality of LoadSeg and as such, patched out the old 
LoadSeg and called the toolbox LoadSeg as part of it's code. Since this is replacing 
LoadSeg, it finishes up by calling the routine in the jump table that generated the call to 


LoadSeg in the first place. 


> eee > Oe ee ee eee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee et ee ee ee ee 


. MOVE.L (A7)+,Al 


; Do whatever we wanted 
MOVE.L AppiScratch, AQ 


BRA.S DoLoadSeg 
BRA.S PastLoadSeg 


d 
f 
f 
f 
f 
f 
f 


NOP 
DoLoadSeg 

JSR (AQ) ; 
PastLoadSeg ; 


A A A ee ee ee ee eee ee ek ee ee eed iy ie ee ee ee 


Save return address of caller. Note 
that since we are replacing LoadSeg we 
may assume that we have been called 
through the jump table. 


to before the real LoadSeg call. 
For this example, assume that before 


; patching the LoadSeg address out, the 


actual LoadSeg address was saved in 
the application scratch area. 

This is the unusual part. 

So is this. 


Call the toolbox LoadSeg. 


Resume execution here. 


; Do anything needed after the LoadSeg call. 


SUBQ.L #6,Al1 


RTS 


I eee ag A A i D S D 


ld 
MOVE.L Al,-(A7) ; 


> Adjust return address to be start of 


the jump table entry that called us. 
Push the return address on the stack. 


; Return (actually, call the routine 


originally called for). 


es ce ee ee oe ce ee ee ee ee ee ee ee ee ee es ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee Ia 


Figure 4 


A code segment showing both a patch to LoadSeg and a call to the old 
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#44: HFS Compatibility Issues 


See also: File Manager Programmer's Guide 
Technical Note #24: Available Volumes and Files 


Written by: Jim Friedlander 10/9/85 
Modified by: Scott Knaster, Jim Friedlander 12/5/85 


This technote tells you how to make sure that your applications will run under 
the new Hierarchical File System (HFS). 


The new Hierarchical File System (HFS) provides for much faster, more efficient 
management of large volumes than the current Macintosh File System (MFS). Since 
HFS is truly hierarchical, folders have taken on a meaning different from MFS folders. 
In MFS, a folder has only graphical significance -- it is only used by the Finder as a 
means of visually grouping files. The MFS directory structure is actually flat (all files are 
at the ‘root’ level). In HFS, a folder is a directory that can contain files and other 
directories. 


A folder is accessed by use of a WORefNum (Working Directory reference number). Calls 
that return a vRefNum when running under MFS may return a WORefNum when running 
under HFS. You may use a WORefNum wherever a vRefNum may be used. 


In order to provide for compatibility with software written for MFS, the HFS calls that 
open files search both the default directory and the directory that contains the System 
file and the Finder (HFS marks this last directory so it knows where to quickly find the 
System file and the Finder). 


Your goal should be to write programs that are File System independent. Your 
programs should not only be able to access files on other volumes, but also files that 
are in other directories. Accomplishing this is not difficult -- most applications that were 
written for MFS work correctly under HFS. If you find that your current applications do 
not run correctly under HFS, you should check to see if you are doing any of the 
following five things: 


1. Are you not using Standard File (SFGetFile, SFPGetFile, SFPutFile, 
SFPPutFile) as described in inside Macintosh? This is very important to ensure 
that your application will run correctly under HFS. HFS uses a new Standard File, 
which allows the user to select from files in different directories. This increased 
functionality was implemented without changing Standard File's external 
specification -- the only difference is that SFReply.vRefNum Can now be a 
WDRefNum. Please note that using Standard File's dialog hook and filter procs or 
adding controls of your own will not cause compatibility problems with HFS. 
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Existing applications that use Standard File properly run without modification 
under HFS. Applications that take the SFReply.vRefNum and convert that to a 
volume name, then append it to SFReply.fName (as in #2 below) do not function 
correctly under HFS -- the user can only open files in the root directory. If you call 
Open with SFReply.vRefNum and SFReply. fName, everything will work correctly. . 
Remember, SFReply.vRefNum may be a WORefNum. 


Current applications that use their own ‘standard file’ routines are unable to 
access directories, thus limiting file access to files in the root directory. Using 
Standard File will virtually guarantee that your application will be compatible with 
MFS, HFS and future Macintosh File Systems. 


2. Are you concatenating volume names to file names, i.e. using file names of the 
form 'VOLUME:fileName'? Applications that do this do not work correctly with 
HFS (in fact, they do not even run correctly under MFS). Instead of this, use a 
vRefNum to access a volume or a directory. Fully qualified pathnames such as 
volume:folderl:folder2:filename will work correctly, but we con't 
recommend that you use them. Please don't ever make a user type in a full 
pathname! 


3. Are you searching directories for files using a loop such as 
FOR index:= 1 to ioVNmFls DO... 
where ioVNmFls was returned from a PBGetVinfo call? This technique should 
not be used. Instead, use the technique illustrated in Technical Note #24, i.e. 
repeated calls to PBGetFInfo using ioFDirIndex until fnfErr is returned. 
Indexed calls to PBGet Finfo will only return the files in the directory specified by 
the vRefNum that you put in the parameter block. 


4. Are you assuming that a vRefNum will actually refer to a volume? A vRefNum can 
now be a WDRefNum. A WDRefNum indicates which working directory (folder) a file 
is in, not which volume the file is on. Don't think of a vRefNum as a way to access 
a volume, but rather as a means of telling the File System where to find a 
particular file. | 


5. Are you walking through the VCB queue? You should let us do the walking for 
you. Using indexed calls to PBGet VInfo will allow you to get information about 
any mounted volume. The reason that you shouldn't walk through the VCB queue 
is that it changed for HFS and might change in the future. The routines that we 
supply will correctly access information in the VCB queue. 


6. (assembly language only) Are you using the File System's "immediate" bit? Inside 
Macintosh describes bit 9 of the trap word as the immediate bit. In fact, setting this 
bit under MFS did not work as documented; it did not have the desired effect of 
bypassing the file /O queue. Under HFS, this bit is used; it distinguishes HFS 
varieties of calls from MFS varieties. For example, the PBOpen call has this bit 
clear: PBHOpen has it set. Therefore, you must be sure that your File System calls 
do not use this bit as the immediate bit. 
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#45: Inside Macintosh Quick Reference 

Compiled by: Jim Friedlander August 2, 1985 

The following technical note is a compilation of all procedures and function calls in the 
most current version of Inside Macintosh. 

An asterisk(*) preceding a procedure/function name means that the routine is not in 
ROM. Two asterisks(**) preceding a manager's name indicate that none uel the 


manager's calls are located in ROM. 


Due to space considerations variable names have been omitted where they don't serve 
a useful purpose, i.e. 'menuHandle’ instead of ‘the Menu:MenuHandle’. 
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#46: Separate Your Resource Files During Development 
See also: Resource Manager Programmer's Guide 


Written by: Bryan Stearns 16 October 1985 


During development with the Lisa Workshop, you use the resource compiler 
(Mac/RMaker.Obj) to convert your resource definition file into an executable Z ZA 
application. Since you rarely change anything but your CODE resources during 
development, RMaker spends a lot of time compiling resources which have not 
changed since they were originally created. This includes dialog, alert, and window 
definitions, as weli as icons, strings, menus, and other resources which are not being 
changed with each build. 


To save time, some developers have adopted the technique of storing all of these 
"static" resources in a separate resource file. This file should be placed on the same 
volume as your application; when your application starts up, use OpenResFile to open 
the separate file. This will cause the resource map for the separate file to be searched 
before the normal application resource file's map (which now contains mostly CODE 
resources, along with any brand-new resources still being tested). 


This will have little or no effect on the rest of your program. Any time that a resource is 
needed, both resource files wili be searched automatically, so you don’t need to 
change each GetResource call (Actually, having the extra resource file open has a 
minor impact on memory management, and uses one more file-contro! block; unless 
you're using a lot of open files at once, or are running at the limits of available memory 
without segmentation, this shouldn't affect you). 


Once your application is close to being finished, you can use ResEdit to move all the 
resources from the separate file, back to the main application file, and remove the extra 
OpenResFile at the beginning of your application. You should do this for any major 
release (alpha, beta, and any other 'heavy-testing' releases). Any other minor 
modifications (such as fine-tuning dialog box item positions) may also be done with 
ResEdit at this time. 


The only catch to all this is that you must be careful if your application adds resources 


to its own resource file. Most applications do not do this (it's not really a great idea, and 
may cause problems later with file servers). | 
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#47: Customizing SFGetFile 
See also: Macintosh Packages Programmer's Guide 


Written by: Jim Friedlander October 11, 1985 


This Technical Note consists primarily of a short example program that 
demonstrates how SFGetFile can be customized using the dialog hook and 
file filter functions. 


SFGetFile's dialog hook function and file filter function enable you to customize 
SFGetFile's behavior to fit the needs of your application. This Technical Note 
consists primarily of a short example program that 


1) changes the title of the Open button to 'MyOpen', 

2) adds two radio buttons so that the user can choose to display either text files or 
text files and applications. 

3) adds a quit button to the SFGetFile dialog, 


All this is done in a way so as to provide compatibility with the Macintosh File System 
(MFS), the Hierarchical File System(HFS) and (hopefully) future systems. If you have 
any questions as you read, the complete source of the demo program and the resource 
compiler input file is provided at the end of this Technical Note. 


Basically, we need to do three things: add our extra controls to the resource compiler 
input file, write a dialog hook function, and write a file filter function. 


Modifying the R rc mpiler input Fil 


First we need to define a dialog in our resource file. It will be DLOG #-4000 (the same 
as Standard File's get dialog in the System File). Since our dialog is ‘higher’ in the 
resource chain, it will be used instead of the DLOG #-4000 in the System File. The 
DLOG looks like this: 


Type DLOG 

774000 (32) 

0 0 200 349 

Invisible 1 NoGoAway 0 
-4000 

GF 


The above coordinates (0 0 200 349) are from the standard Standard File dialog. If you 
need to change the size of the dialog to accommodate new controls, change these 
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coordinates. Next we need to add a DITL in our resource file that is the same as the 
standard HFS DITL #-4000 except for one item. We need to change the left coordinate 
of Useritem #4, or part of the dialog will be hidden if we're running under MFS: 


*4 left coordinate changed from 232 to 252 so program will 
* work on MFS 

UserItem Disabled 

39 252 59 347 


None of the other items of the DITL should be changed, so that your program will 
remain as compatible as possible with different versions of Standard File. Finally, we 
need to add three items to this DITL, two radio buttons and one button (to serve as a quit 
button) 


* ll -- textButton 
RadioItem Enabled 
1 14 20 142 

Text files only 


* 12 -- textAppButton 
RadioItem Enabled 

19 14 38 176 

Text and applications 

* 13 ~- quitButton 
BtnItem Enabled 

6 256 24 336 

Quit 


Because we've added three items, we need also need to change the item count for the 
DITL from 10 to 13. We also include the following in our resource file: 


Type STR# 
7,256 
MyOpen 


That's all there is to modify in the resource file. 


The Dialog Hook 
We will be calling SFGet File as follows: 
SFGetFile (wher, '', @SFFileFilter, NumFileTypes, 
MyFileTypes, @MySFHook, reply); 
Notice that we're passing @MySFHook to standard file. This is the address of our dialog 
hook routine. Our dialog hook is declared as: 


FUNCTION MySFHook(MySFitem: INTEGER; theDialog: DialogPtr) : INTEGER; 


A dialog hook routine allows us to see every item hit before standard file acts on it. This 


Technical Note #47 page 2 of 8 Customizing SFGetFile 


allows us to handle controls that aren't in the standard SFGetFile's DITL or to handle 
standard controls in non-standard ways. The dialog hook in this example consists of a 
case statement with MySFPitem as the case selector. Before sFGetFile displays its 
dialog, it calls our dialog hook, passing ita -1 as MySFitem. This gives us a chance to 
initialize our controis. Here we will set the textAppButton to off and the textButton to on: . 


GetDitem(theDialog, textAppButton, itemType, itemToChange, itemBox) ; 
SetCtiValue (controlHandle (itemToChange) ,btnOff); 
GetDitem(theDialog, textButton, itemType, itemToChange, itemBox) ; 
SetctlValue (controlHandle (itemToChange) , btnOn) ; 


and we can also change the title of an existing control. Here's how we might change 
the title of the "Open’ button using a string that we get from a resource file: 


GetIndString (buttonTitle,256,1); 

If buttonTitle <> '' then Begin l { if we really got the resource} 
GetDitem(theDialog, getOpen, itemType, itemToChange, itemBox) ; 
SetCtitle (controlHandle (itemToChange),buttonTitle) ; 

End; {if} {if we didn't get the resource, don't change the title } 


Upon completion of our routine that handles the -1, we return a -1 to standard file: 
MySFHook:= MySFItem; {pass back the same item we were sent} 


We now have a SFGetFile dialog displayed that has a quit button and two radio 
buttons (the ‘textOnly’ button is on, the ‘TextApp’ button is off). in addition, the 
‘standard’ Open button has been renamed to ‘'MyOpen’ (or whatever STR is the first 
string in STR# 256). This was all done before SrGetFile displayed the dialog. Once 
our hook is exited, SFGetFile displays the dialog and calls ModalDialog. 


When the user clicks on an item in the dialog, our hook is called again. We can then 
take appropriate actions, such as highlighting the textButton and un-highlighting the 
textAppButton if the user clicks on the textButton. At this time, we can also update a 
global variable (textoOnly) that we will use in our file filter function to tell us which files 
to display. Notice that we can redisplay the file list by returning a 101 as the result of 
MySFHook. For example, the textButton is hit -- we turn the textAppButton off, turn the 
textButton on, update the global variable textOnly, and tell sFGetFile to redispiay 
the list of files the user can choose from: 


if not textOnly then Begin {if textOnly was turned off, turn it on now} 
GetDItem(theDialog, textAppButton, itemType, itemToChange, itemBox) ; 
SetCtlValue (controlHandle (itemToChange) ,btnOff) ; 
GetDitem(theDialog, textButton, itemType, itemToChange, itemBox) ; 
SetCtlValue (cont rolHandle (itemToChange) , btnOn) ; 
textOnly:=TRUE; {toggle our global variable for use in the filter} 
MySFHook:= reDrawList; {101} {we must tell SF to redraw the list} 

End; {if not textOnly} 


if our quit button is hit, we can pass SFGetFile back the cancel button: 


MySFHook:= getCancel; 


If one of SFGetFile's standard items is hit, it is very important to pass that item back to 
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SFGetFile: 
MySFHook:= MySFItem; {pass back the same item we were sent} 


The File Filter 


Remember, we called SFGetFile as follows: 


SFGetFile (wher, '', @SFFileFilter, NumFileTypes, 
MyFileTypes, @MySFHook, reply); 


Notice that we're passing @SFFileFilter toSFGetFile. This is the address of our 
file filter routine. A file filter is declared as: 


FUNCTION SFFileFilter (p: ParmBlkPtr): BOOLEAN; 


A file filter routine allows us to control which files SFGet File will display for the user. 

Our file filter is called for every file (of the type(s) specified in the typelist) on an MFS 
disk, or for every file (of the type(s) specified in the typelist) in the current directory on an 
HFS disk. In addition, sFGet File displays HFS folders for us automatically. Our file 
filter selects which files should appear in the dialog by returning FALSE for every file 
that should be shown and TRUE for every file that shouldn't. For example, using our 
global variable textOn1ly (which we set in our dialog hook, remember?) : 


FUNCTION SFFileFilter(p:parmBlkPtr) :boolean; 


Begin {SFFilerilter} | 
SFFileFilter:= TRUE; {Don't show it -~- default) 


if textOnly then 
if p*.ioFlFfndrinfo.fdType = "TEXT' then 
SFFileFilter:= FALSE {Show TEXT files only} 
else Begin 
End {dummy else} 
else 
if (p*.ioFlFfndrinfo.fdType = "TEXT') or 
(p*.ioFlFndrinfo.fdType = 'APPL') then 
SFFileFilter:= FALSE; { show TEXT or APPL files} 
End; {SFFileFilter} 


SFGetFile calls the file filter after it has called our dialog hook. Please remember that 
the filter is passed every file of the types specified in the typelist (MyFileTypes). If you 
want your application to be able to choose from all files, pass srGetFile a -1 as 
numTypes. For information about parameters to SFGetFile that haven't been 
discussed in this technica! note, see the Macintosh Packages Programmer's Guide. 


That's ali there is to it! Now that you know how to modify sFGet File to suit your needs, 
please don't rush off and load up the dialog window with all kinds of controis and text. 
Please make sure that you adhere to Macintosh interface standards. Similar 
techniques can be used with SFPGetFile, SFPutFile and SFPPutFile. 


The complete source of the demo program and of the resource compiler input file 
follows: 
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Th mo Proara 
{$X~} 
{$U—} 
{$R-} 


{Jim Friedlander Macintosh Technical Support 9/30/85} i 


program SFGetDemo; 


USES 
{SU Obj/Memtypes } Memtypes, 
{$U Obj/QuickDraw } QuickDraw, 
{$0 Obj/OSIntf } OSintf, 
{$0 Obj/TooliIntf } ToolIntf, 
{80 Obj/PackIntf } Packintf; 

{$D+} 

VAR 


where to display dialog } 

reply record } 

tells us which files are currently being displayed} 
we won't actually use this } 


wher: Point; 

reply: SFReply; 
textOnly: BOOLEAN; 
myFileTypes: SFTypeList; 
NumFileTypes: integer; 


"n ie gin r 


FUNCTION MySFHook (MySFitem:integer; theDialog:DialogPtr): integer; 


CONST 

textButton = E (DITL item number of textButton} 

textAppButton = 12; {(DITL item number of textAppButton} 

quitButton = 13; {(DITL item number of quitButton} 

stayInSF = 0; (if we want to stay in SF after getting an Open hit, 
we can pass back a 0 from our hook (not used in 
this example) } 

firstTime = =l}; {the first time our hook is called, it is passed a 


~-1} 


{The following line is the key to the whole routine -~ the magic 101!!} 


reDrawList = 101; {returning 101 as item number will cause the 
file list to be recalculated} 
btnon = 1; {control value for on} 
btnofft = 0; {control value for off} 
VAR 
itemToChange: Handle; {needed for GetDItem and SetCtlValue} 
itemBox;: Rect ; {needed for GetDItem} 
itemType: integer; {needed for GetDIitem} 
buttonTitle: Str255; {needed for GetIndString} 


Begin (MySFHook } 
case MySFItem of 


firstTime: Begin { before the dialog is drawn, our hook gets called 
with a -1 (firstTime) as the item so we can change 
things like button titles, etc. } 


{Here we will set the textAppButton to OFF, the textButton to ON} 


GetDItem(theDialog, textAppButton, itemType, itemToChange, itemBox) ; 
SetCtlValue(controlHandle (itemToChange}, btnOff); 
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GetDitem(theDialog, textButton, itemType, itemToChange, itemBox) ; 
SetctlValue(controlHandle (itemToChange) , btnOn); 


GetIndString (buttonTitle,256,1); 
(get the button title from a resource file} 
If buttonTitle <> '' then Begin { if we really got the resource} 
Get DItem (theDialog, getOpen, itemType, itemToChange, itemBox}; {get a handle to the 
open button} 
SetCtitle {controlHandle (itemToChange),buttonTitle) ; 


End; {if} {if we can't get the resource, we just won't change 
the open button's title} 


MySFHook:= MySFiItem; {pass back the same item we were sent} 
End; ({firstTime} : 


{Here we will turn the textAppButton OFF, the textButton ON and redraw the list} 
textButton: Begin 
if not textOnly then Begin 
Get DItem(theDialog,textAppButton, itemType, itemToChange, itemBox) ; 


SetCtlValue (controlHandle(itemToChange) ,btnOfft); A 
GetDitem(theDialog,textButton, itemType, itemToChange, itemBox) ; 
SetCtlValue (controlHandle(itemToChange),btnOn); 
textOnly: TRUE; 
MySFHook:= reDrawList; {we must tell SF to redraw the list} 
End; {if not textOnly} 
End; {textOnlyButton} 
(Here we will turn the textButton OFF, the textAppButton ON and redraw the list} 
textAppButton: Begin 
if textOnly then Begin 
GetDItem (theDialog, TextButton, itemType, iremToChange, itemBox) ; 
SetCtlValue (controlHandle(itemToChange}, Btnoff); 
GetDiItem (theDialog, TextAppButton, itemType, itemToChange, itemBox) ; 
SetCtlValue (controlHandle(itemToChange) , BtnOn) ; 
TextOnly:*FALSE; 
MySFHook:= reDrawList; {we must tell SF to redraw the list} 
End; {if not textOnly} 
End; {textAppButton} 
quitButton: MySFHook:= getCancel; {Pass SF back a 'cancel button'} 
{ttt twvery important !!!! We must pass SF's ‘standard’ item hits back to SF} 
otherwise Begin 
MySFHook:= MySFitem; { the item hit was one of SF's standard items... } 
End; {otherwise} { so just pass it back} 


End; {case} 
End; {MySFHook} 


FUNCTION SFFileFilter(p:parmBlkPtr) :boolean; {general strategy -~ check value of global var 
textOnly to see which files to display} 


Begin ({SFFileFilter} 
SFFileFilter:= TRUE; {Don't show it -- default} 


if textOnly then 
if p*.ioFlFndriInfo.fdType = 'TEXT’ then 


SFFileFiilter:= FALSE {Show it} 
else Begin 
End {dummy else} 
else 
if (p*.ioFlFndrinfo.fdType = ‘TEXT') or (p*.ioFlFndrinfo.fdType = 'APPL') then 
SFFileFPilter:= FALSE; {Show it} i 
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End; {SFFileFilter} 


~ 


{----- men nn nnn nnn nn aaa } 


Begin {main program} 
InitGraf (@€thePort); 
InitFonts; 
InitWindows; 

TEInit; 
InitDialogs (nil); 


wher .h:280; 
wher.v:=90; 
NumFPileTypes:= -1; {Display all flies} 


{ we don't need to initialize MyFileTypes, because we want to get a chance to filter every file 
on the disk in SFFileFilter ~ we will decide what to show and what not to. If you want to 
filter just certain types of files by name, you would set up MyFileTypes and NumFileTypes 
accordingly} 


repeat 
textOnly:= TRUE; {each time SFGetFile is called, initial display will be text-only files} 
SFGetFile (wher, '', @SFFileFilter, NumFileTypes, MyFileTypes, @MySFHook, reply); 
until reply.good = FALSE; 
{until we get a cancel button hit ( or a Quit button ~- thanks to our dialog hook ) } 
End. 


The Resource Compiler Input File 


t resource definition file for SFGetDemo.text 
SFGetDemo.rsre 


Type DLOG 
274000 (32) 
0 0 200 349 
Invisible 1 NoGoAway 0 
-4000 
GF 


Type DITL 
,74000 (32) 

13 

* 1 

Btnitem Enabled 

138 256 156 336 


Open 


* 2 

BtnItem Enabled 

1152 59 1232 77 

Hidden ; 


* 3 

BtnIitem Enabled 
163 256 181 336 
Cancel 


* 4 left coordinate changed from 232 to 252 so program will work on MFS 
UserItem Disabled 
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39 252 59 347 


x 5 

Btnitem Enabled 
68 256 86 336 
Eject 


* 6 

Btnitem Enabled 
93 256 111 336 
Drive 


t 7 
UserItem Enabled 
39 12 185 230 


* 8 
UserItem Enabled 
39 229 185 245 


® 9 
UserItem Disabled 
124 252 125 340 


* 10 
StatText Disabled 
1044 20 1145 116 


teaxene The following items were added to SF's standard items ******* 


* 11 

RadioItem Enabled 
1 14 20 142 

Text files only 


a 12 

Radioitem Enabled 

19 14 38 176 

Text and appiications 
* 13 

BtnItem Enabled 

6 256 24 336 

Quit 


Type STR# 
,256 


MyOpen 


Type CODE 
SFGet DemoL, 0 
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#48: Bundies 
See also: Putting Together a Macintosh Application 
Written by: Ginger Jernigan 11/1/85 





This technical note gives a definitive description of what a bundle really is 
and how to create your own. 





So what is a bundle anyway? A bundle's primary function in life is to tie an icon to a file 
type, allowing your application or data file to have its own customized icon in the Finder. 
This technote describes how to create a bundle and how a bundle is used by the 
Finder. 


How to Create a Bundle 


A bundle is a collection of resource types. To create one we need to invent some input 
for a resource compiler, like RMaker. (We could use ResEdit instead, but that's too 
easy.) In our input file we need to set up three types of resources: an ICN#, an FREF, 
and a BNDL. Let's start with the ICN# (most people do). 


The ICN# resource type is an icon list. Each ID can have a number of icons associated 
with it. For file icons, there are two icons associated with an ID: one for the icon itself 
and one for the mask. Let's say for this example we have two file types, each having its 
own icon. To define the icons for these files we would enter this into our resource input 
file: | 


Type ICN# 
,/32 * this is the ID for the first icon 
2 * two icons for this ID, the icon and the mask 


_* this is the icon 
FFFFFFFF “icons are defined as 32 rows of 8 hex digits representing the icon 
FOOSCDD 


FFFFFFFF 

* now for the mask 

FFFFFFFF  * same as above, 32 rows of 8 hex digits 
FFFFFFFF 

FFFFFFFF 


,733 * now for the second icon and mask 
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2 * two icons for this ID, the icon and the mask 
OFOFOFOC 

FFFFFFFF 

* and the mask 

FFFFFFFF 

FFFFFFFF 


Now that we've defined our icons we can set up the FREFs. An FREF is a file reference. 
It ties a file type to a local ID number. Our FREF will look like this: 


Type FREF 

816 * this is the ID for the first file type 
APPL 0 * the type is APPL, the local ID is 0 
O17 * this is the ID for the second file type 
TEXT 1 * the type is TEXT, the local ID is 1 


Aha! | see that questioning look in your eyes saying "So what is a local ID anyway?" 
Well, it goes like this: Local IDs are used by the Finder to identify file types and 
associated resources. Local IDs aren't the same as Resource IDs. You do not use them 
to access a particular resource from the Resource Manager. 


Now for the bundle. The resource type is BNDL and it looks like this: 


Type BNDL 
128 * this is the ID of the bundle 
MINE 0 * MINE is the bundle owner (the creator) 
2 * we have two types in this bundle 
ICN# 2 * the first type is ICN# and we have two of them 
0 732 * local ID 0 maps to ICN# ID 732 
1 733 * local ID 1 maps to ICN# ID 733 
FREF 2 * the second type is FREF and there are two of those too 
0 816 * local ID 0 maps also to FREF ID 816 
1817 * local ID 1 maps also to FREF ID 817 


What does all this mean? It means that all of the local ID Os are associated (bundied) 
with one another, and the local ID 1s are associated (bundled) with one another. When 
you are in the Finder, your application, type APPL (#816), will be displayed with icon 
#732. Files of type TEXT (#817) created by your application will be displayed with icon 
#733. 


How the Finder Uses Bundles 


Let's talk briefly about how the Finder uses a bundle. When the Finder encounters a file 
type it needs to display, it looks up the type in the Desktop file. The Desktop file is used 
by the Finder to keep track of all of the pertinent information about how to display the 
documents on a volume. If the Finder finds a bundle for the file in the Desktop file then it 
uses the associated icon to display the file. If it can't find a bundle, then it uses the 
default document or application icon. 
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if the file is an application that has the bundle bit set, but the bundle isn't in the Desktop 
file, the Finder makes a copy of the bundle and puts it in the Desktop file. The 
application is then displayed with its associated icon. 


lf a data file has lost its icon (it's on a disk without the application and the Desktop file 
was trashed), then it will be displayed with the default document icon until the Finder 
encounters a copy of the application that contains the right bundle. The Finder then 
makes a copy of the application's bundle and places it in the Desktop file of the data 
file's disk. 


lt was originally thought that if file types were bundled together, then when one file was 
copied, using the Finder, the other would be copied implicitly. These files were called 
"tag along” files and were mentioned briefly in old Inside Macintosh documentation. 
These "tag along” files were never implemented. 


Problems That May Arise 


There are times when you have set up these three resource type properly but for some 
reason the icon is either the wrong one or it has defaulted to the standard application or 
data file icon. There are a number of possible reasons for this. 


The first thing to check is whether there are any extraneous spaces in your resource 
compiler input file. The Macintosh-based RMaker is very picky about extra spaces. 


If your icon is defaulting to the standard icons, did you set the bundle bit when you 
copied the file from the Workshop to the Macintosh disk using Maccom? If you don't set 
the bundle bit, the Finder doesn't know to place the bundle in the Desktop file. If it isn't 
in the Desktop file, the Finder displays it with a default icon. 


What if you changed the icon and remade the resource file, but the file still has the same 
old icon when displayed in the Finder. This means that the old icon is still in the Desktop 
file. The Finder doesn't know that you've changed it, so it uses what it has. To get it to 
use the new icon you need to delete the old Desktop file. You can do this either by 
making the file visible in FEdit and throwing it away or by deleting it in Maccom or 
ResEdit. 


Have a bundle of fun! 
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#50: ResLoad 


See also: Resource Manager Programmer's Guide 
Technical Note #1: Desk Accessories and System 
Resources 
Written by: Jim Friedlander October 25, 1985 





Calling SetResLoad (FALSE) can be useful if you need to get a handie to a resc Ss 
without causing the resource to be loaded from disk if it isn't already in memory. ihis 
technique is used by Technical Note #1. SetResLoad changes the value of the 
low-memory global ResLoad (at location $A5E). 


It is very important that your program not leave ResLoad set to FALSE when it exits. 
Doing this will cause the system to reboot or crash when it does a GetResource Call for 
the next code segment to be loaded (usually the Finder). The system will crash 
because GetResource will not actually load the code from disk when ResLoad is 
FALSE. 


So, make sure that you call SetResLoad (TRUE) before exiting your program. 
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#51: Debugging using PurgeMem and CompactMem 
See also: Memory Manager's Programming Guide 


Written by: Jim Friedlander October 19, 1985 





if you are having problems finding things like handles that aren't locked down when 
they should be, or resources that aren't there when they're supposed to be, there is a 
very handy technique for forcing these problems to the surface. Every time through the 
main event loop call: 


PurgeMem (MaxSize) ; {MaxSize = $800000} 
size:= CompactMem (MaxSize); 


PurgeMem will purge all purgeable blocks and CompactMem will rearrange the heap, 
trying to find a contiguous free block of MaxSize bytes. Obviously, this will move things 
around quite a bit, so, if there are any unlocked handles that you have de-referenced, 
you will find out about them very quickly. 


Don't be alarmed when you see the performance of your program deteriorate drastically 
-- it's just because lots of resources are being loaded and purged every time through 
the main event loop. You might want to have a debugging menu item that toggles 
between glacial and normal execution speeds. 


Please be sure to remove these two lines from any code that you ship!! In fact, neither 


of these two calls should normally be made from your application. They tend to undo 
work that has been done by the Memory and Resource Managers. 
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#52: Calling _Launch From a High-Level Language 
See also: The Segment Loader 


Written by: Jim Friedlander November 2, 1985 





it is very easy to call Launch and _Chain from any high-level language that 
allows inline assembly code, such as most C's and Lisa Pascal. 





The Segment Loader chapter in Inside Macintosh says about _Launch and _Chain: 
"The routines below are provided for advanced programmers; they can be called only 
from assembly language". While this is technically true, it is very easy to call _Launch 
and Chain from any high-level language that allows inline assembly code, such as 
most C's and Lisa Pascal. This technical note demonstrates how to call Launch and 
_Chain from Lisa Pascal. 


The inline code is needed because Pascal is a stack-based language and we need to 
have parameters to _Launch and _Chain put in register AO: AO must contain a handle 
to the application's file name and 4(A0) must contain the configuration parameter 
(normally 0) that determines whether the application will use an alternate screen buffer 
and an alternate sound buffer. While using these alternate buffers may be 
advantageous under certain circumstances, be aware that the Macintosh XL doesn't 
support them and future machines may not support them either, so you should avoid 
using them. 


We need the following data structure: 


TYPE 
pLaunchStruct = “LaunchStruct; 
LaunchStruct = record 
pfiName: “*Str255; 
param: integer; 
End; {LaunchStruct} 


and the following variabies: 
VAR 
pMyLaunch: pLaunchStruct; 
myLaunch: lLaunchStruct; 
fName: Stxr255; 
Next we need to declare our inline procedure, which takes a variable of type 
pLaunchStruct as a parameter. A pointer to this parameter will be pushed on the 
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stack. We then need code to put this pointer into register AO. The instruction to do that 
iS MOVE.L (SP)+,A0, which is $205F in hex, SO the first word after ‘INLINE’ is $205F. 
This will set things up so that we're ready to call Launchor_ Chain, as (A0) contains a 
pointer to the fileName and 4(A0) contains the configuration parameter, so the last part 
of the inline, $A9F2 is the trap for Launch. If you want to use _Chain, simply use an - 


SA9F3 instead: 


PROCEDURE LaunchIt (pLnch: pLaunchStruct) ; INLINE $205F, SA9F2; 
{or if you want, $205F, $A9F3 for Chain} 


{ The inline code does the following: 
MOVE.L (SP)+,A0 ; pop pointer to launch structure 


_Launch 


} 


All that remains for us to do is to set up our Pascal variables. Please remember that 
_Launch will only launch an application on the current volume, SO you'll need to do a 
Set Vol, if necessary, before the call to Launchit. We need to point our pointer at the 


launch data structure: 
pMyLaunch:= @myLaunch; 
assign the file name: 
fName:= ‘FileToLaunch’; 
then we need to set up the two fields of the launch variable: 


With pMyLaunch* do Begin 
pfName:= @fName; {pointer to our fileName} 
param:= 0; {we don't want alternate screen or sound buffers} 
End; {With} 
and now we just do a: 


Launchit (pMyLaunch) ; 
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- #53: MoreMasters Revisited 
See also: Memory Manager Programmer's Guide 


Written by: Jim Friedlander October 28, 1985 





MoreMasters Should be called from CODE segment 1. The number of times 
that MoreMasters should be called can be determined empirically. 


a a aaa 


If you ask Macintosh programmers when and how many times MoreMasters should be 
called, you will get a variety of answers, ranging from ‘four times in the initialization 
segment ' to ‘once, anywhere’. As you might suspect, the answer is somewhat different 
from either of these. P 


MoreMasters allocates a block of master pointers in the current heap zone. In the 
application heap, a block of master pointers consists of 64 master pointers; in the 
system heap, a block consists of 32 master pointers. Since master pointer blocks are 
non-relocatable, we want to be sure to allocate them early. The system will allocate 
one master pointer block as your program loads. It's the first object in the application 
heap -- its size is $108 bytes. 


A lot of programmers call MoreMasters from an ‘initialization’ segment, but as we shall 
see, that's not such a good idea. The problem occurs when we unioad our ‘initialization’ 
segment and it gets purged from memory. The following diagrams of the application 
heap illustrate what happens if we call MoreMasters from CODE segment 2 (MPB 
stands for Master Pointer Block): 
























Before MoreMasters After MoreMasters After CODE 2 is purged 
Free Free | Free 
High Heap Heap Heap 
Memory Space 
, Mep-3108 P MPB-$108 GY 
SSS SS 
| cope 1 CODE 1 f 
ES aOR Se Se ct 
ZZMPB-$108 UY 





non-relocatable locked 
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Notice that we now have some heap fragmentation -- not serious, but it can be avoided 
by making all MoreMasters calls in CODE segment 1. Because InitWindows creates 
the Window Manager Port (WMgr Port), it should also be called from CODE segment 1. 
Both MoreMasters and InitWindows should be called before another CODE segment ` 
is loaded, or the non-relocatable objects they allocate will be put above the CODE 
segment and you'll get fragmentation when the CODE segment is purged. if you want 
to call an initialization segment before calling MoreMasters and InitWindows, make 
sure that you unload it before you call either routine. 


Now that we know when to call MoreMasters, how many times do we call it? The 
answer depends on your application. If you don't call MoreMasters enough times, the 
system will call it when it needs more master pointers. This can happen at very 
inconvenient times, causing heap fragmentation. lf you call MoreMasters too often, 
you can be wasting valuable memory. This is a however, to allocating too few 
master pointer blocks! 


The number of times you should call MoreMasters can be empirically determined. 
Once your application is almost finished, remove all MoreMasters calls. Exercise your 
application as completely as possible, opening windows, using handles, opening desk 
accessories, etc. You can then go in with a debugger and see how many times the 
system called MoreMasters. You do that by counting the non-relocatables of size 
$108. Due to Memory Manager size correction, the master pointer blocks can also have 
a size of $10C or $110 bytes. You should give yourself about 20% leeway -- that is, if 
the system called MoreMasters 10 times for you, you should call it 12 times. If you're 
more cautious, you might want to call MoreMasters 15 times. 


This is a simple strategy for handling MoreMasters. The program ResEdit uses a far 


more sophisticated approach, allocating master pointer blocks dynamically. That 
technique will be the subject of a future Technical Note. 
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#54: Limit to Size of Resources 


See also: Resource Manager Programmer's Guide 
Programming in Assembly Language 
Memory Manager Programmer's Guide 


Written by: Jim Friedlander October 23, 1985 


ae 


Theoretically, resources can be very large -- the size can be a signed 32-bit int r, 
Due to a bug in the Resource Manager, there is currently a more severe size limitation 
of 32K bytes. The problem is in the interaction between WriteResource and the trap 
dispatcher. WriteResource does the following: 


40DEB2: _GetHandleSize 
BPL.S Q1 
MOVEQ 0,D0 ; force zero length (purged!) 
@1 


GetHandleSize returns the (32 bit) size of the handle in DO. The problem is that the 
trap dispatcher does the following before returning: 


40107E: TST .W DO 
RTS 


Because many OS calls return an error code in the low word of DO, the trap dispatcher 
does a TST.W DO to set the 68000's condition code register. In the case of 
GetHandleSize, the value in DO is a long word (it's not actually an error code, but the 
size of the handle). What we really need is either a TST.L here, ora TST.L before 
the BPL.S in WriteResource. Because a TST.W DO is being done, any call to 
WriteResource where bit 15 of the resource size is set, results in a resource of size 0 
because the TST.wW DO will set the condition code registers negative bit. Since the 
negative bit is set, the BPL.S @1 will not be taken. This means that resources 
between 0 and 32K in size will work OK, between 32K and 64K will not, between 64K 
and 96K will, and so on... 


Of course, if you are calling GetHandleSize in your code, make sure that you watch for 
the same problem. 
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SetRect (icnRect,0,0,32,32); { define the icon's 'bounds'} 
With iBitMap do Begin 
baseAddr:= @MyILHnd1**.icon; 
rowbytes:= 4; { 4 * 8 =32} 
bounds:= icnRect; 
End; {with} 
With mBitMap do Begin 
baseAddr:= @MyILHnd1** .mask; 
rowbytes:= 4; 
bounds:= icnRect; 
End; {with} 


icons can represent desktop objects that are either selected or not. Folder and volume 
icons can either be open or not. The object (or the volume it is on) can either be online 
or offline. The Finder draws icons using all permutations of open, selected and online: 
















Non-Open 
Non-Selected 


Open 
Non-Selected 


Offline 


Drawing icons as ‘non-open’ is basically the same for online and offline volumes. We 
need to ‘punch a hole’ in the desktop for the icon. This is analogous to punching a hole 
in dough with an irregular shaped cookie-cutter. We can then sprinkle jimmies” all over 
the cookie and they will only stick in the area that we punched out (the mask). We do 
this by copyBitting the mask onto the desktop (whatever pattern) to our destRect. For 
‘non-open, non-selected' icons: 


we use the SrcBic mode so that we punch a white hole: 


SetRect (destRect, left, top, left+32,topt32); 
CopyBits (mBitMap, thePort*.portBits, icnRect,destRect,SrcBic,NIL); 


Then we XOR in the icon: 
CopyBits (iBitMap, thePort*.portBits, icnRect, destRect, SrcXor,NIL) ; 


That's all there is to drawing an icon as 'non-open, non-selected’. To draw the icon as 
‘non-open, selected’: 


we will OR in the mask, causing a mask-shaped BLACK hole to be punched in the 
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desktop: 

CopyBits (mBitMap, thePort*.portBits, icnRect,destRect,SrcOr,NIL) ; 
Then, as before, we XOR in the icon: 

CopyBits (iBitMap, thePort*.portBits, icnRect, destRect, SrcxOr,NIL) ; 


To draw icons as 'non-opened' for offline volumes: 





we need to do a little more work. We need to XOR a ItGray pattern into the 'boundsRect' 
of the icon. We will then punch the hole, draw the icon and then XOR out the ltgray 
pattern that does not fall inside the mask. So, to draw the icon as ‘offline, non-open, 
non-selected' we would: 


GetPenState (OldPen) ; {save the pen state so we can restore it} 
PenMode (patXor); 
PenPat (1tGray) ; 
PaintRect (destRect) ; {paint a ltGray background for icon} 


CopyBits (mBitMap, thePort*.portBits, icnRect,destRect, SrcBic,NIL) ; {punch } 
PaintRect (destRect); {XOR out bits outside of the mask, leaving the mask} 
{filled with itGray} 

CopyBits (iBitMap, thePort*.portBits,icnRect,destRect,SrcOr,NIL); { OR in } 
{ the icon to the ltGray mask} 

 SetPenState (OldPen) ; {restore the old pen state} 


To draw the icon as ‘offline, non-open, selected’: 





we would use a similar approach: 


GetPenState (OldPen); { save the pen state so we can restore it} 
PenMode (patXor) ; 

PenPat (dkGray) ; { the icon is selected, so0 we need dkGray } 
PaintRect (destRect); { paint a dkGray background for icon } 
CopyBits (mBitMap, thePort*.portBits,icnRect,destRect,SrcecBic,NIL) ; {punch } 


PaintRect (destRect); {XOR out bits outside of the mask, leaving the mask} 
{filled with dkGray} 

CopyBits (iBitMap, thePort*.portBits, icnRect,destRect,SrcBic,NIL); {BIC the} 
{icon to the dkGray mask} 

SetPenState (OldPen) ; {restore the old pen state} 


Drawing the 'opened' icons requires one less step. We don't have to CopyBits the 
icon in, we just use the mask. Online and offline icons are drawn the same way. To 
draw icons as ‘open, selected’: 





we do the following: 
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GetPenState (OldPen) ; {save the pen state so we can restore it} 
PenMode (pat Xor) ; ` 
PenPat (dkGray); { the icon is selected, so we need dkGray } 
PaintRect (destRect); { paint a dkGray background for icon} 
CopyBits (mBitMap, thePort*.portBits, icnRect,destRect, SrcBic,NIL); {punch} 
PaintRect (destRect); {XOR out bits outside of the mask, leaving the mask} 
{filled with dkGray} 
SetPenState (OldPen) ; {restore the old pen state} 


To draw icons as ‘open, non-selected': 





we just need to change one line from above. Instead of XORing with a dkGray pattern, 
we use a ItGray pattern: 


PenPat (1ltGray) ; { the icon is non-selected, so we need 1tGray } 


These techniques will work on any background, window-white or desktop-gray and all 
patterns in between. Have fun. 


* jimmies : little bits of chocolate 
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#56: Break/CTS Device Driver Event Structure 


See also: Device Manager 
Serial Drivers 
Zilog Z8030/Z8530 SCC Serial Communications Controller 
Technical Manual 


Written by: Mark Baumwell 12/02/85 


This Technical Note documents the event record information that gets 
passed when the Serial Driver posts a device driver event for a break/CTS 
status change. 


The Serial Driver can be programmed to post a ‘device driver event’ upon encountering 
a break status change or CTS change (via the SerHShake Call). The structure of device 
driver events is driver specific. This Technical Note documents the event record 
information that gets passed when the Serial Driver posts a device driver event for a 
break/CTS status change. 


When the event is posted, the message field of the event record will be a long word 
(four bytes). The most significant byte will contain the value of SCC Read Register 0 
(see below for the relevant Read Register 0 values). The next byte will contain the 
changed (since the last interrupt) bits of the SCC read register 0. The lower two bytes 
(word) will contain the pct 1RefNum. 


The values for Read Register 0 are as follows: 


¢ Ifa break occurred, bit 7 will be set. 
¢ If CTS changed, bit 5 will reflect the state of the CTS pin (a 0 means the 
handshake line is asserted and that it is "OK to transmit”). 


We discourage posting these events because interrupts would be disabled for a long 
time while the event is being posted. However, it is possible to detect a break or read 
the value of the CTS line in another way. A break condition will always terminate a 
Serial Driver input request (but not an output request), and the error ‘breakRecd’ (-90) 
will be returned (this constant is defined in the SysEqu file.). You could therefore detect 
a break by checking the returned error code. 


The state of the CTS line can be checked by making a SerStatus call and checking 


the value of the ctsHold flag in the SerStaRec record as per the Serial Drivers chapter 
of Inside Macintosh. 
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#57: Macintosh Plus Overview 


See also: File Manager (Alpha Draft 12/6/85) 
Written by: Scott Knaster January 8, 1986 
Modified by: scott Knaster January 29, 1986 





This document gives an overview of the Macintosh Plus from a software 


developer's point of view. X 
a S 





The Macintosh Plus differs from a Macintosh 512K computer in these features: 


e it contains an enhanced 128K ROM 

e it includes an internal 800K, 3.5 inch disk drive, with an optional 800K external drive 
e it has 1 Megabyte of RAM as a standard feature 

e it has a built-in SCSI (small computer standard interface) connector 

e it includes an expanded keyboard with arrow keys and numeric pad 

e its serial ports are 8-pin DIN connectors 


Important warning: the information in this document is believed to be correct, but 
may contain errors. Please watch for future technical notes and other communications 
concerning updates and corrections. In addition, you'll find places in this document 
which mention features only briefly; further information on these features will be 
available from Apple in the future. 


128K_ ROM 


Macintosh Plus is designed to be compatible with most existing Macintosh software. No 
change which would cause a significant number of existing applications to fail was 
implemented. Overall, the 128K ROM has had three basic design goals: 


1. Maintain compatibility with existing software 
2. Enhance performance 
3. Fix bugs 


Warning: be sure to verify that new ROMs are installed in the machine 


you're running on before attempting to use any of the new features. 
See the "Miscellaneous Notes” section for information on how to do this. 
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Resource Manager 


The Resource Manager has been generally speeded up. Compacting a resource file is 
now smarter and therefore much, much faster. There is a new “supercharging" 
capability which allows specially formatted applications to start up faster due to mass 
reads. It also uses various caching techniques to minimize disk access. Apple will 
provide information on “supercharging" application resource files in the future. 


The ROM now contains several commonly used resources; see the "Miscellaneous 
Notes” section of this document for more information. 


To optimize your resource loading with the new Resource Manager: 

e Anticipate which resources will be loaded by which ROM calls. Group resource 
loads by file to avoid disk thrashing. 

e Use the one-deep calls (see below) 

e If you're modifying a series of resources, use a "get one, change it, get another, 
change it" method instead of "get ‘em all, change ‘em all.” 

- Similarly, when changing resAttrs on lots of resources, use a “one at a time” 
method. 

e If you're using Get IndResource, cycle your index from 1 to N instead of N 
down to 1. 


SetResPurge now works on theZone rather than ApplZone. 
Note that the “resource reference” capability and the AddReference and 
RmveReference Calls have been removed. 


New calls 


CountiResources, Toolbox 13 (SA80D) 
Get lIndResource, Toolbox 14 (SA8QE) 
CountlTypes, Toolbox 28 (SA81C) 
GetlindType, Toolbox 15 (SA80F) 
UniquelID, Toolbox 16 ($A810) 
GetiResource, Toolbox 31 (SA81F) 

Get 1NamedResource, Toolbox 32 ($A820) 


All the above functions are "“one-deep” calls, i.e. they function identically to their 
standard counterparts (including external interfaces), except that they only search the 
current resource map, then give up. This allows for faster searches if you only want to 
search CurMap. 


MaxSizeRsrc, Toolbox 33 (S$A821); 
FUNCTION MaxSizeRsre (theResource:Handle): LONGINT; 


Figures out the size of a resource by seeing how much space there is between map 
entries. This allows a program to determine a resource’s size without causing a disk 
read. The name comes from the fact that the resource may actually be smaller, but not 
yet compacted. 


Technical Note #57 page 2 of 20 Macintosh Plus Overview 


RsrcMapEntry, Toolbox 453 (SA9C5) 
FUNCTION RsrcMapEntry (theResource:Handle): LONGINT; 


This function returns the location of a resource's entry in the resource map. The 
location is given as an offset from the beginning of the map, returned in the function 
result. Caution: be careful when playing with resources directly! 


OpenRFPerm, Toolbox 452 (S$A9C4) 
FUNCTION OpenRFPerm (fileName: Str255; VRefNum: 
INTEGER; permission :byte) 
: INTEGER; 


This is an extended version of OpenResFile. It opens the resource file with the given 
filename, vRefNum, and permission (as defined by the File Manager). It returns the 


resource file's reference number. If the function result is negative, there will be an error 
code in resErr. 


QuickDraw 


Performance Enhancements 


QuickDraw's performance has been improved substantially. Here are the measured 
ratios of old drawing speed to new drawing speed for several areas of performance: 


Paragraph of Text 1.50 
CopyBits Aligned 1.35 
Copybits (region -> rect) 2.30 
CopyBits Stretching, general 1.30 
CopyBits Stretching, selected ratios 3.40 
FillRect 1.44 
InvertRect 1.32 
Slanted Lines 2.29 
Vertical Lines (region -> rect) 4.98 
PaintOval 2.19 
FrameOval 2.14 
PaintRRect 1.71 
FrameRRect 1.58 
Bug Fixes 


The following bugs have been fixed: 


Rect InRgn used to sometimes return true when the rect was in the region's bounding 
box but not in the region. 


SectRgn, DiffRgn, UnionRgn, XorRgn and FrameRgn used to cause a stack 
overflow for regions with more than 25 rectangles in one scanline. 
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Pt ToAngle didn't work right when angle = 90 and aspect ratio was a power of two. 


In some cases where CopyBits source bitmap overlapped its destination, the transfer 
would clobber the source bitmap before it was used. 


If you tried to draw a long piece of shadowed text with a tall font, QuickDraw would die if 
there wasn't enough stack space for the required off-screen buffer. Now it detects the 
potential stack overflow and recurses on the left and right halves of the text. 


CopyBits and ColorMap used to die if thePort was odd or Nil. 


DrawText did not work correctly with pictures if the character count was greater than 
255. 


New Capabiliti 
Fractional Spacing for Text: 


In order to more accurately represent the fine character spacing available on the 
LaserWriter, the Font Manager has extended the font format to allow for fractional 
character spacing. Each string drawn with QuickDraw will take an integer number of 
pixels, but within a string not all "i" characters will be spaced the same number of pixels 
apart. Old fonts without fractional spacing should behave the same. The Font Manager 
has also added several new flags to control spacing and font substitution behavior, 
including a new default which allows character spacing to stretch without the ugly 
effects of bitmap stretching. 


Text Modes: 


Previously only three transfer modes, srcOr, srcBic, and srcXor modes were 
supported for text drawing. Now all eight transfer modes are allowed. In the newly 
allowed modes, QuickDraw does not put extra slop on the right to handle italic 
characters. 


ColorBit has been changed so that a negative value will turn off all color mapping. 
This prevents green text on a red background from coming out black on black for a 
black and white display. 


Pictures can now have a size that's a long word (over 4 gigabytes). To get the size of a 
picture, use Get HandleSize instead of looking at the picSize field, which for 
compatibility contains the low 16 bits of the real size. Old code will work fine for pictures 
up to 32767 bytes. To check if you ran out of memory during picture creation, test 
EmptyRect (picFrame). If this returns true, the picture is empty. 
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New calls 


SeedFill, ToolBox 57 £($A839) 
PROCEDURE Seed@Fill(srcPtr,dstPtr: Ptr; 
srcRow, dstRow,height,words: INTEGER; 
seedH, seedV: INTEGER); 


Given an input bitmap, SeedFil1l computes an output bitmap with ones only in the 
pixels where paint can leak from the starting seed point, like the MacPaint paint bucket 
tool. Calls to SeedFill are not clipped to the current port and are not stored in 
QuickDraw pictures. 


CalcMask, Toolbox 56 ($A838) 
PROCEDURE CalcMask (srcPtr,dstPtr: Ptr; 
srcRow, dstRow,height,words: INTEGER); 


Given an input bitmap, CalcMask computes an output bitmap with ones only in pixels 
where paint could not leak from any of the the outer edges, like the MacPaint lasso tool. 
Calls to CalcMask are not clipped to the current port and are not stored in QuickDraw 
pictures. 


CopyMask, Toolbox 23 ($A817) 
PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; 
srcRect,maskRect,dstRect: Rect); 


This is a new version of CopyBits which transfers bits from the source bitmap to the 
destination bitmap only where the corresponding bit of the mask bitmap Is a one. It can 
be used along with CalcMask to implement the lasso copy as in MacPaint. It is also 
useful for drawing icons. Calls to CopyMask don't check for source and destination 
overlap, don't stretch, and are not stored in QuickDraw pictures, but they do respect the 
current port's visRgn and clipRgn if dstBits is the current portBits. 


MeasureText, Toolbox 55 ($A837) 
PROCEDURE MeasureText (count: INTEGER; textAddr,charLocs:Ptr); 


This procedure is designed to improve performance in specialized applications like 
word processors by providing an array version of TextWidth. CharLocs should point 
to an array of count+1 integers and will be filled in with the TextwWidth of the first 0, 1, 2 
... count characters of the text pointed to by textAddr. 


Note: MeasureText only works with text displayed on the screen; it does not go 


through QuickDraw's StdText bottleneck, so it can't be used for text that’s going to be 
printed. 
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GetMaskTable, Toolbox 54 ($A836) 


$0000,$8000,$C000,$E000 
$F000,$F800,$FC00,$FE00 
$FFOO,$FF80,$FFCO,$FFEO 
$FFFO,$FFF8,$FFFC,$FFFE 


$FFFF,$7FFF,$3FFF,$1FFF 
$OFFF,$07FF ,$03FF,$01FF 
$OOFF,$007F ,$003F,$001F 
$000F,$0007,$0003,$0001 


$8000,$4000,$2000,$1000 
$0800,$0400,$0200,$0100 
$0080,$0040,$0020,$0010 


Loads Ao with a pointer to a ROM table containing the following useful masks: 


‘Table of 16 right masks 


“Table of 16 left Masks 


‘Table of 16 bit masks 


WORD $0008,$0004,$0002,$0001 


Font Manager 


The Font Manager now supports many new features, including the ability to have 
fractional character widths, a new font numbering scheme, performance enhancements, 
and more. Many of the new features are implemented through the use of a new 
resource type, FOND, which specifies an entire font family. 


w call 


SetFScaleDisable, Toolbox 52 ($A834) 
PROCEDURE SetFScaleDisable (scaleDis:BOOLEAN) ; 


Sets the low-memory global FScaleDisable according to the boolean parameter. 
Also sets CurFMFamily to -1. 


FontMetrics,53 ($A835) 
PROCEDURE FontMetrics (VAR theMetrics:FontMetricRec)}) ; 


Returns fractional information about the current font as specified in thePort. It returns 
a Font Metric Record whose format is: 


ascent: Fixed; 
descent: Fixed; 
leading: Fixed; 
widMax: Fixed; 


WTabHandle: Handle; 
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Window Manager 


There is a new variant of the standard window definition procedure (WDEF 0) which 
allows you to implement window zooming out to full-screen size and zooming back in to 
the pre-zoomed size. There is also new support in the Window Manager itself to 
implement this capability. See Finder 5.1 for a demonstration of this capability. 


New calls 


TrackBox, Toolbox 59 ($A83B) 
FUNCTION TrackBox (window: windowPtr; thePt: Point; 
partCode: INTEGER) : BOOLEAN. . 


The standard window defproc (WDEF 0) has a new variant (code 8) which creates a 
window with a zoom box. The zoom box is an icon which appears in the right corner of 
the title bar. When there's a mouseDown in this location, the Window Manager will 
return the code inZoomOut (8). You should then call TrackBox with partCode = 
inZoomOut, just the way you would call TrackGoAway. If the function result is true, the 
user released the mouse in the zoom box, and you should call ZoomWindow (see 
below). 


lf the window has already been zoomed out and there's a mouseDown in the zoom box, 
the part code returned will be inZoomin (7). Once again, you should call TrackBox, 
this time with partCode = inZoomIn, and call ZoomWindow if TrackBox returns true. 


ZoomWindow, Toolbox 58 (S$A83A) 
| PROCEDURE ZoomWindow (window: windowPtr; partCode: 
integer; front: BOOLEAN) ; 


Call this procedure if TrackBox returns true. The window will either be zoomed out or 
in, according to the partCode and its current state. If it's already in the state specified by 
the partCode, nothing happens. If front is true, the window will be brought to the front; 
otherwise it will be left where it is. 


Control Manager 


New call 


UpdtControls, Toolbox 339 ($A953) 
PROCEDURE UpdateControls(theWindow: windowPtr; 
update: RgnHandle); 


This procedure is used to draw all the controls of a given window that are in the 
specified update region. Most useful for scrolling windows that contain controls. 
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Menu Manager 


MENU resources must not be made purgeable. In the 64K ROM, purged MENUs were 
not detected --- the system just assumed they were never purged and died at its 
convenience. In the 128K ROM, a purged MENU will cause a system error #84, 
MenuPrgErr, when the Menu Manager tries to use it. 


AddResMenu now alphabetizes the resources before putting them into the menu. 
InsertResMenu also alphabetizes, but only within the inserted range, not the entire 
menu. 


The new menu definition function, MDEF 0, which is in ROM, includes a new feature for 
menus with lots of items. If the menu is so long that the entire menu cannot be drawn on 
the screen, dragging below the last item will cause the items in the menu to auto-scroll 
up; similarly, if items have scrolled off the top, dragging up from the top item will cause 
the menu to auto-scroll down. Previously, 20 items could be drawn in a menu; the new 
MDEF will draw up to 19. 


New calls 
InsMenulItem, Toolbox 38 ($A826) 


PROCEDURE InsMenuItems (MenuHandle: Handle; 
itemstring: str255; itemNum: INTEGER); 


Inserts the items in the itemstring after the specified item (to insert at beginning, pass 
item of 0). ItemString is parsed just like the itemstring in AppendMenu. Multiple items 
are inserted in the reverse of their order in the string. 


DelMenuItem, Toolbox 338 ($A952) 
PROCEDURE DelMenulItem(MenuHandle:Handle; itemNum: 
INTEGER) ; 


Deletes the specified item from the specified menu. 
TextEdit 
TextEdit now has horizontal and vertical autoscrolling in the default clikLoop. Since 


there's no way to update a scroll bar from within this default clikLoop, this feature is 
useful mainly for dialogs which contain editable text items. 


New calls 


TESelView, Toolbox 17 ($A811) 
PROCEDURE TESelView (hTe: TEHandle); 


Makes sure that the selection is in viewRect; scrolls it in if not. If Autoview (see below) 
is false, does nothing. Mainly useful in dialogs. 
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TEPinScroll, Toolbox 18 ($A812) 
PROCEDURE TEPinScroll (dh,dv: INTEGER; h: TEHandle) ; 


Just like old TEScroll, except that it stops scrolling (pins) when the last line scrolls into 
the viewRect. 


TEAUtoView, Toolbox 19 ($A813) 
PROCEDURE TEAutoView (auto: BOOLEAN;hTe: TEHandle) ; 


Sets the AutoView flag (used by TESelView) according to the boolean parameter. 
This flag enables/disables TESe1View and autoscrolling in the default clikLoop. 


Dialog Manager 


New calls 


HideDItem, Toolbox 39 ($A827) 
PROCEDURE HideDItem (dialog: dialogPtr; itemNo: INTEGER) ; 


Hides the specified item by adding $2000 toits rect.left and rect.right. Erases 
and invals the item. If it's the active editText item, deactivates it first. If it's a control, 
calls MoveControl. If it's already hidden, does nothing. 


ShowDItem, Toolbox 40 ($A828) 
PROCEDURE ShowDItem (dialog: dialogPtr; itemNo: INTEGER); 


Shows the specified item by subtracting $2000 from its rect.left and rect.right. 
If it becomes the only edit Text item, activates it. If it's a control, calls MoveControl. If 
it's not hidden, does nothing. 


UpdtDialog, Toolbox 376 ($A978) 
PROCEDURE UpdtDialog(dialog: DialogPtr; 
updateRgn: rgnHandle) ; 


Draws the items that are in the update region. Should be bracketed by 
BeginUpdate/EndUpdate to fix the update region. 


FindDItem, Toolbox 388 ($A984) 
| FUNCTION FindDItem (dialog: dialogPtr; thePoint: 
Point): INTEGER; 


Returns the number of the item under the specified point. If no item found, returns —1 as 
the item number. thePoint must be in local coordinates. 


Desk Manager 


The Desk Manager now passes events of type 0 through 11 to desk accessories. 
Previously, only events 0 through 8 were passed. 
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Scrap Manager 


The scrap is now written on the boot disk (in the System Folder if it's an HFS volume), 
rather than the default volume. 


ToolBox Utilities 


Fix 


Point Math 


Type Fract allows very accurate representation of small numbers (-2<n<2). A Fract Is 
a 32-bit number, with the following format: 


bit 31 sign 
bit 30 integer part 
bits 29..0 fractional part 
n ion _routin 
Long2Fix, Toolbox 63 (SA83F) 
FUNCTION Long2Fix (x: longint): Fixed; 
Fix2Long, Toolbox 64 ($A840) 
FUNCTION Fix2Long (x: Fixed): longint; 
Fix2Frac, Toolbox 65 (5A841) 
FUNCTION Fix2Frac (x: Fixed): Fract; 
Frac2Fix, Toolbox 66 (SA842) 
FUNCTION Frac2Fix (x: Fract): Fixed; 
Fix2X, Toolbox 67 ($A843) 
FUNCTION Fix2X (x: Fixed): Extended; 
X2Fix, Toolbox 68 ($A844) 
FUNCTION X2Fix (x: Extended): Fixed; 
Frac2Xx, Toolbox 69 ($A845) 
FUNCTION Frac2X (x: Fract): Extended; 
X2Frac, Toolbox 70 ($A846) 
FUNCTION X2Frac (x: Extended): Fract; 
FracCos, Toolbox 71 ($A847) 
| FUNCTION FracCos (x: Fixed): Fract; 
Returns Cos (x) 
FracSin, Toolbox 72 ($A848) 
FUNCTION FracSin (x: Fixed): Fract; 
Returns Sin(x) 
FracSqrt, Toolbox 73 (SA849) 
FUNCTION FracSqrt (x: Fract): Fract,; 
Returns square root of x 
FracMul, Toolbox 74 (SA84A) 
FUNCTION FracMul (x, y: Fract): Fract; 
Returns x*y 
FracDiv, Toolbox 75 (SA84B) 
FUNCTION FracDiv(x, y: Fract): Fixed; 
Returns x/y 
FixAtan2, Toolbox 24 (S$A818) 
FUNCTION FixATan2 (x, y : LongInt): Fixed; 
Returns ATan(y/x) 
FixDiv, Toolbox 77 (SA84D) 
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FUNCTION FixDiv (x, y: Fixed): Fixed; 
Returns x/y, signed 


Package Manager 


New calls 


Pack8, Toolbox 22 ($A816) 

Pack9, Toolbox 43 (SA82B) 

Pack10, Toolbox 44 (SA82C) 
Packli, Toolbox 45 ($A82D) 
Pack12, Toolbox 46 (SA82E) 
Pack13, Toolbox 47 (SA82F) 
Pack14, Toolbox 48 (S$A830) 
Pack15, Toolbox 49 ($A831) 


The Package Manager has been extended to allow for 16 packages instead of the 
previous 8. The new packages are reserved for use by Apple. 


Standard File Package 


Standard File looks very different visually, but has retained the same external interface 
for programming. Standard File also includes many new user features: it supports 
directional keys, for example. See the HFS Programmer's Package for full details on 
the new Standard File. 


Memory Manager 
All Memory Manager calls now report errors directly to the system global MemErr. 


There is a new pair of calls to set and clear the status of the resource bit in a master 
pointer (bit 5). Existing calls (HPurge, HNoPurge, HLock, HUnlock) let you change 
the other two bits, the purge and locked bits. In addition, there is a pair of calls to get 
and set the entire flags byte (only the three bits mentioned are used now --- the others 
are reserved for future use by Apple). 


Important: You should no longer use BSET and BCLR instructions to directly set and 
clear these bits; instead, you should use the six set-and-clear calls and the 
get-and-set-save-state calls. These calls will always be supported; Apple will not 
guarantee that the flag bits will be in the same place in future systems for direct BSET 
and BCLR. 


w çall 
HSetRBit, OS 103 ($A067) 
Given a handle, sets resource bit in master pointer. 


entry: AO.L contains handle 
exit: DO.w contains error code 
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HClrRBit, OS 104 (SA068) 

Given a handle, clears resource bit in master pointer. 
entry: AO.L contains handie 
exit: DO.w contains error code 

HGetState, OS 105 ($8069) 

Given a handle, returns its master pointer's flags byte. 
entry: AO.L contains handle 
exit: DO.B contains flag byte 


HSetState, OS 106 (SAOQO6A) 


Given a handle and a flag byte, sets its master pointer's flags byte. 


entry: AO .L contains handle 
DO.B contains new flags byte 
exit: DO.wW contains error code 


MaxBlock, OS 97 ($A061) 
_MaxBlock 


Returns maximum available free space that could be allocated without purging or 
growing the heap zone. Most effective after calling MaxApplZone. 

entry: (none) 

exit: DO.L contains size of block that could be allocated. 


PurgeSpace, OS 98 (SA062) 
_Purgespace 


Returns the sum of free and purgeable bytes in the heap zone, as weil as the maximum 
possible contiguous chunk which would be available after purging. 
entry: (none) 
exit: DO.L contains sum of purgeable and free bytes in zone 
AO.L contains maximum possible contiguous space after purge 


MaxApplZone, OS 99 (SA063) 
_MaxApp1Zone 


Grows the heap zone to App1 Limit. 
entry: (none) 
exit: DO contains O (no error) 
This call was previously available in Pascal glue. 


MoveHHi, OS 100 (SA064) 
_MoveHHi 
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Moves a relocatable block as high as possible (i.e., as far up as possible without 
passing a locked or nonrelocatable block). Uses significant stack space (about 1K). 
entry: AO is a handle to the block to be moved 
exit: DO contains the error code 


This call was previously available in Pascal glue. 


StackSpace, OS 101 (SA065) 
_StackSpace 


Returns remaining stack space available (i.e., space between A7 and HeapEnd). 
entry: (none) 
exit: DO.L contains the available stack space 


NewEmptyHandle, OS 102 (SA066) 
_NewEmpt yHandle 
_NewEmptyHandle, SYS 


Creates an empty relocatable block in the heap zone. An optimized special case of 
NewHandle. (This routine is used mainly by the Resource Manager.) 
entry: (none) 
exit: AO contains the handle to the new block 
DO contains the error code 


Segment Loader 


The LoadSeg routine has been revised to add a capability that should dramatically 
reduce fragmentation. If a code segment (resource of type CODE) is not marked as 
locked in the resource file (in other words, its resLocked bit is clear), the Segment 
Loader will automatically move the segment up in memory by calling MoveHHi before 
locking the segment. Since current development environments automatically mark 
CODE as locked, you'll have to use ResEdit to mark your CODE resources unlocked. 
You should leave CODE 1 locked. 


SCSI Manager 


This new part of the ROM handles the devices plugged into the SCSI port on the back of 
the Macintosh. 


There are 9 SCSI Manager calls which are accessed through a single trap. To call the 
routines, first push the parameters on the stack, then push a selector word, then call the 
SCSIDispatch trap. 


New calls 


SCSIDispatch, Toolbox 21 ($A815) 
_SCSIDispatch 
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routine selectors: 
0 = SCSIReset 1 = SCSIGet 2=scSiISelect 3=SCSICmd 
4 = SCSIComplete 5 = SCSIRead 6 = ScSIWrite 8= SCSIRBlind 
9 = SCSIWBlind 

FUNCTION SCSIReset : OSErr; 

Resets the SCSI bus. 

FUNCTION SCSIGet : OSErr; 

Arbitrates for the use of the SCSI bus. 

FUNCTION SCSISelect (TargetID: INTEGER): OSErr; 

Select the SCS! target that has the given ID. 

FUNCTION SCSICmd (Buffer: Ptr; Count: INTEGER): OSErr; 

Send Count bytes of the command pointed to by Buffer. 


FUNCTION SCSIComplete (VAR Stat, Message: INTEGER; 
Wait: LONGINT): OSErr; 


Delay for Wait ticks waiting for the current command to complete, and fill stat 
and Message with the two SCSI completion bytes. 


FUNCTION SCSIRead (tibPtr: Ptr): OSErr; 


SCS|Read transfers data from the target to the initiator, as specified in the transfer 
instruction block pointed to by tibPtr. 


FUNCTION SCSIWrite (tibPtr: Ptr): OSErr; 


SCSIWrite transfers data from the initiator to the target, as specified in the 
command descriptor block pointed to by tibPtr. 


FUNCTION SCSIRBlind (tibPtr: Ptr): OSErr; 
FUNCTION SCSIWBlind (tibPtr: Ptr): OSErr; 


These functions are similar to the preceding two calls, except that the /REQ line on 
the SCS! bus is polled and waited for only on 512-byte boundaries. 


Note: More information about the SCSI Manager will be available soon. Please 
contact Macintosh Technical Support if you need further information. 
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File Manager (Hierarchical File System) 


New calls 


HFSDispatch, OS 96 (SA060) 
_HFSDispatch 


Calls new HFS routines. (Note: MFS is Macintosh File System, the “old” file system). 


entry: DO contains call selector for pure HFS calls: 

1 = OpenWD 2 = ClosewD 5 = CatMove 6 =DirCreate 
7 =GetWDInfo 8=GetFCBInfo 9=GetCatInfo 10=SetCatInfo 
11 =HSetVolinfo 

AO points to parameter block 


Note: in general, you should avoid these calls and use the MFS calls. This will allow 
your code to work with both File Systems. Most applications will rarely, if ever, need to 
use the HFS calls. Get FCBInfo can be used on MFS volumes. 


A global variable called FSFCBLen at $3F6 can be used to determine if HFS is installed. 
If not, this location (a word) will contain $FFFF. If HFS is installed, this location will 
contain a positive signed integer which gives the length of a file control block (currently 
$5E). 


Existing calls (Open, for example) use trap word bit 9 ("IMMED") to denote HFS vs. 
MFS (set for HFS flavor, clear for MFS); e.g., $A200 for the HFS version of Open. 


Warning: Note that in MFS, the IMMED bit was supposed to cause the call to bypass 
the queue, but in fact, it did nothing. If you have existing code which uses IMMED, you 
should rewrite it to not set this bit. 


For most calls, the only difference in the HFS flavor is that you get to specify a directory 
ID (ioDirID at 48(A0) ). You should avoid these calls, in general, so that your 
application can work with both file systems. 


See new File Manager Alpha Draft of 12/6/85 and Technical Note #44, HFS 
Compatibility Issues, both available in the HFS Programmer's Package, for more 
information. 


Operating System Utilities 
New calls 


RelString, OS 80 ($A050) 
_RelString (same interface as _CmpString) 
FUNCTION RelString(str1l,str2: Str255; 
caseSens,diacSens: BOOLEAN): integer; 
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Just like CmpString, except it indicates sorting order of strings; CmpString only tells 
whether they're equal. This function is used mainly by the File Manager to create a 
universal ordering for file names. Applications should use the International Utilities to 
compare strings according to local rules. 


‚MARKS means set trap word bit 9 (ignore diacriticals) 
,CASE means set trap word bit 10 (case is significant) 
entry: AO points to first character of first string 
A1 points to first character of second string 
DO high word contains length of first string 
DO low word contains length of second string 
exit: DO.L contains 
-1 if first string is "less than" (sorts before) second string, 
0 if strings are equal, 
1 if first string is "greater than” (sorts after) second string 


Since Toolbox traps and OS traps can now share trap numbers (see “Miscellaneous 
Notes section"), Set TrapAddress and GetTrapAddress have been modified. Bit 9 of 
the trap word, previously unused, is now used to indicate old ROM or new ROM trap 
numbering. If bit 9 is zero, these calls will assume the old ROM trap numbering; in other 
words, trap number 0 is always Open ($A000), trap number 50 is always InitCursor 
($A050), and so on. If bit 9 is one, the state of bit 10 determines whether this call refers 
to an OS trap (bit set to 1) or a Toolbox trap (bit is set to 0). For example, 


_SetTrapAddress ($A047) respects old ROM ordering; 
_SetTrapAddress with bit 9 set ($A247) sets OS Trap 
_SetTrapAddress with bits 9 & 10 set ($A647) sets Toolbox trap 


Binary-Decimal Conversion Package (included in ROM) 


This package now includes calls to convert between SANE decimals and Pascal and C 
strings. | 


New calls 


PStr2Dec, Package 7, call 2 
PROCEDURE PStr2Dec (s: DecStr; VAR index: INTEGER; VAR d: 
decimal; VAR validPrefix: Boolean); 


CStr2Dec, Package 7, call 4 
PROCEDURE CStr2Dec (s: CStrPtr; VAR index: INTEGER; VAR d: 
decimal; VAR validPrefix: Boolean); 


Dec2Str, Package 7, call 3 
PROCEDURE Dec2Str (f: DecForm; d: Decimal; VAR s: DecStr); 


Call the first two procedures with index set to the first character to scan. These calls 


will return with index set to the first character beyond the end of a valid decimal string 
and the decimal record set to the converted decimal value. If the rest of the string, from 
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the new index value to the end of the string, is a valid number, validPrefix is set to 
TRUE. 


Disk Initialization Package 
The Disk Initialization package can format 400K or 800K disks. When disks in 
double-sided drives are formatted, the dialog will give the user a choice of formats. 


Remember that 400K volumes have flat catalogs and 800K and larger volumes are 
hierarchical. 


Miscellaneous notes 

How to Call New ROM Routines 

A forthcoming software supplement will include interface files and equates for the new 
ROM. Until then, you can easily construct your own interfaces by using the Pascal 
"Inline" feature. To do this, just declare the ROM procedure or function, followed by 
"Inline" and the trap word, like this: 


FUNCTION TrackBox (window: windowPtr; thePt: Point; partCode: 
INTEGER) : BOOLEAN; Inline $A83B; 


Warning: this technique only works for stack-based (that is, Toolbox) calls. It will not 
work for O.S. calls, such as Memory Manager and File Manager routines. Note that 
interfaces for the new File Manager are available in the HFS Programmer's Package 
(price $25) from Apple. 

Caching 


The File System now has a general caching mechanism. The size of the cache is set by 
the Control Panel. Information on caching will be available in future technical notes. 


Booting 

When booting, the Macintosh Plus first checks the internal drive. If that fails, it tries the 
external drive. If that fails, it tries SCSI devices, starting with device 0. If that fails too, it 
puts up the blinking question mark. 


List Manager 


The system now includes a new package, the List Manager, which is used to help draw 
one and two-dimensional lists of data, like the list of files in Standard File. 


Escape from disk-switch request 


When the Macintosh requests another volume, you can escape from the request by 
pressing <command>-<period>. Note that many applications will get confused by this, 
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and will either ask again repeatedly or die, so use this feature with caution. 
INIT Mechanism 


When the system starts up, it looks for files with types INIT and RDEV in the system 
folder. If it finds any, it looks in those files for resources of type INIT. If it finds any of 
those, it executes them. 


New Chooser 


The Choose Printer desk accessory has been replaced by the more powerful and 
general Chooser. The Chooser is used to select among devices on a network and to 
assign a user name as well as selecting devices on ports. 


New Control Panel 


The Control Panel desk accessory has been modified. It's now used to turn AppleTalk 
on and off and to set the size of the system cache. 


New Key Caps 


The Key Caps desk accessory now detects which keyboard is attached and changes its 
display appropriately. It also adds a new Font menu which allows you to display 
different fonts in 12 point size. 


New Installer 


The Installer program is a general resource-installation utility. It's highly recommended 
that you use two drives when you run the Installer. 


Global flag for new ROMs 


To determine if the machine you're running on has the new ROMs, test location $28E 
(called ROM85). If the new ROMs are installed, this location will have $7FFF; otherwise it 


will be sFFFF. Don't make any new calls or assume the new ROM 
without verifying this flag first. 


Trap dispatch table and trap words 


The trap dispatch table has been expanded. Instead of a packed format, trap addresses 
are now unpacked long words. There are actually two tables: the OS Table at 
$400-7FF and the Toolbox table at $C00-13FF. 


Note that the ROM now uses bit 11 as the definitive way to distinguish between OS and 
Toolbox traps. Previously, each trap number was either an OS trap or a Toolbox trap, 
but not both. For example, trap $11 was always Get Eof, and trap $65 was always 
_GetPixel. Now, there is a Toolbox trap $11 (new call_TESelView, trap word $A811) 
as well as OS trap $11 (still Get EOF, trap word $A011); there's a Toolbox trap $65 (still 
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_GetPixel, trap word $A865), and an OS trap $65 (new call StackSpace, trap word 
$A065). 


This means that there are now 256 different OS traps ($Ax00 through SAxFF, where X 
varies depending on parameter bits) and 512 different Toolbox traps ($a800 through 
SA9FF). Bit 9 of Toolbox traps is reserved by Apple for future use and should be set to 
zero. 


Resources in ROM 


The 128K ROM includes many system resources that were RAM-based in the original 
system. This list includes: 


DRVR 9 (.MPP) DRVR 10 (.ATP) DRVR 4 (.Sony) 
DRVR 3 (.Sound) DRVR 2 (.Print) | 
SERD 0 (serial drivers) 7 
CDEF 0 (button) CDEF 1 (scroll bar) 


MDEF 0 (text menus) 

WDEF 0 (standard window) 

PACK 4 (SANE) PACK 5 (Elems) PACK 7 (BinDec) 
CURS1 CURS2 CURS3 


The ROM routines look first in the ROM resource map for resources. This is done by 
setting the flag ROMMapInsert at $B9E to $FF and TempResLoad at $B9F to SFF 
if you want TempResLoad true, or by setting $B9F to $00 if you want TempResLoad 
false. Set this flag before calling GetResource Of LoadResource when preflighting 
resource sizes. When you get the handie, you can call HomeResFile on it; the file 
reference number of the ROM resource map is 1. If HomeResFile returns a 1, you know 
that the resource is in ROM. 


WARNING: As with all the new features, be sure that you're running on 128K ROMs 
before setting ROMMapInsert. Under the old ROMs, this location is in the middle of a 
master pointer block in the system heap! 


More HFS Info 


When HFS is installed, volumes with 800 blocks (400K bytes) or fewer will be initialized 
as MFS volumes; larger volumes will get HFS directories. You can force a 
newly-initialized 400K disk to have an HFS volume by initializing it, then typing its 
volume name in the disk init dialog, then pressing <Option>-<Return> to end the dialog. 


An HFS volume may have a special folder which contains system files (usually named 
System Folder). A folder which becomes "blessed" as this special folder must contain 
files named System and Finder. These are the rules: 


e a newly formatted volume has no "blessed" folder (obviously) 

e if the user copies System and Finder into a folder, that folder is “blessed”, and 
the system will look in that folder when booting from that volume 

e that folder remains the "blessed" folder, even if new files named System or 
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Finder are copied into other folders on that volume 
e if either System or Finder is removed from the folder, the folder is "un-blessed" 
e if both System and Finder are moved into a new folder, either one at a time or 
together, the old folder is "un-blessed”, and the new folder becomes the 
"blessed" folder 
¢ the root level can be the "blessed" folder it if follows these rules. 
An HFS volume must have this folder for the volume to be bootable. 
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#57a: Macintosh Plus Overview(update) 


See also: File Manager (Alpha Draft 12/6/85) 
SCSI Manager (Alpha Draft 2/5/86) 
List Manager Package (Alpha Draft 2/5/86) 


Written by: Scott Knaster January 8, 1986 
Modified by: Scott Knaster January 29, 1986 
February 25, 1986 





This document gives an overview of the Macintosh Plus from a software 
developer's point of view. 


Significant changes since last revision: 
e Please see Inside Macintosh drafts for information on the SCSI 
Manager and the File Manager. 
e Segment Loader discussion was rewritten. 
¢ The description of NewEmpt yHandle was changed. 





Segment Loader 


The LoadSeg routine has been revised to add a capability that can dramatically reduce 
fragmentation. If a code segment (resource of type CODE) is unlocked, the Segment 
Loader will automatically move the segment up in memory by calling MoveHHi before 
locking the segment. To take advantage of this feature, you should call MaxApplZone 
at the start of your application. 


Note that when a code segment is initially loaded into memory, it's locked if the 
resource attribute called resLocked is set for that segment (most development systems 
set this bit automatically when creating code resources). When the Operating System 
loads a resource with the resLocked attribute set, it attempts to place that resource low 
in memory. Because of these actions, this is the behavior of code segments: 


64K ROM: If a code segment has resLocked set, it will initially be loaded low, 
then will "float" when unlocked and loaded again. If the code segment does not have 
resLocked set, it will be loaded at a random location and will be locked there, 
fragmenting the heap. 
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128K ROM: If a code segment has resLocked set, it will initially be loaded low. 
When loaded again, it will be moved high before being locked. If the code segment 
does not have resLocked set, it will be loaded high initially and remain there. 


To summarize this behavior, your code segments should have resLocked Set if 
your application will be used on both 64K and 128K ROMs (most development systems 
automatically set resLocked). If your application will only be used on 128K ROMs, your 
code segments should have resLocked Clear. In any case, CODE 1 should always 
have resLocked set, since it's loaded while the heap is small and therefore should be 
forced low. 


Memory Manager 


NewEmptyHandle, OS 102 (SA066) 
_NewEmpt yHandle 
_NewEmptyHandle, SYS 


‘Reserves’ a handle from the free list and sets it to NIL. (This routine is used mainly by 
the Resource Manager.) 
entry: (none) 
— exit: AO contains the handle to the new block 
DO contains the error code 
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#58: International Utilities Package Bugs 
See also: International Utilities Package Routines 


Written by: Jim Friedlander January 24, 1986 





Versions of the Pack6 calls IUCompString, IUEqualString, IUMagString and 
IUMagIDString in system files up to and including the 5/85 Build disk do not properly 
save register D3. If your program is counting on D3 being preserved around calls to 
these routines, you must take steps to save and restore D3 yourself. If you are 
programming in assembly language, you already know how to do this — just save them 
on the stack. 


If you are using Lisa Pascal, you can use INLINEs to accomplish this. We need two 
INLINEs, one to push D3 onto the stack , one to pop it from the stack after the routine is 
called. 

We can declare: 


PROCEDURE SaveD3; INLINE $2F03; {$2F03 = MOVE.L D3,-(SP) } 
PROCEDURE RestoreD3; INLINE $261F; {$261F = MOVE.L (SP)+,D3} 


then, we just need to bracket any of the above four calls with SaveD3 and RestoreD3: 


SaveD3; 
result:= IUCompString(strl1,str2); {as an example} 
RestoreD3; 


Since you don't know which system file the user will be running from, you should take 
these precautionary steps in your code. If you are familiar with assembly language, you 
can check your code to see if it actually uses D3, and then decide whether or not you 
need to bracket calls to these four routines with a save and restore of D3. 
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#59: Pictures and Clip Regions 
see also: QuickDraw 


Written by: Ginger Jernigan January 16, 1986 





This technical note describes a bug that affects the drawing of QuickDraw 
pictures. 





The one problem in QuickDraw that almost all programmers run into has to do with 
clip regions. The problem is that when a grafport is created, the fields in the 
grafport are given default values. One of these is the Clip region, which is set to 
(-32767, -32767, 32767, 32767). If you create a picture, then call DrawPicture with 
a destination rectangle that is not the same size as the picframe without ever 
changing the default clip region, then nothing will be drawn. 


The reason is that when the picture frame is compared with the destination rectangle 
and the picture is scaled, the clip region ends up being scaled too. In the process of 
scaling, the clip region you end up with is empty, and your picture doesn't get drawn. 
This is a problem on both the 64K and 128K Macintosh ROMs. If you just call 
ClipRect (thePort*.PortRect) (you could use any sufficiently large rectangle 
you like) any time before you draw the picture, the picture will then be drawn 
correctly. The only thing you have to be careful of is that if you set the clip before you 
create the picture, that clip will be recorded, possibly affecting the final outcome of 
the picture. 
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#60: Drawing Characters in a Narrow GrafPort 
See also: QuickDraw 


Written by: Ginger Jernigan January 20, 1986 


if you create a narrow grafPort and then attempt to draw a character into that grafPort, 
your program will die with an address error if the width of the grafPort is smaller than the 
width of the character. This occurs on 64K and 128K Macintosh ROMs. If you check 
before drawing the character to see if the grafPort is wide enough then you can : ~ J 
this unfortunate tragedy. 
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#61: GetltemStyle Bug 
See also: The Menu Manager 


Written by: Jim Friedlander January 21, 1986 





It is possible to generate an address error when calling the Menu Manager routine 
GetItemStyle (PROCEDURE GetItemStyle(theMenu: MenuHandle; item: 
INTEGER; VAR chStyle: Style). The problem is not with your code, but with the 
64K ROM. One of the first things that Get ItemStyle does is to clear the variable 
parameter that you pass to it. Variables of type style occupy one byte in memory. To 
clear out chStyle, the ROM clears out two bytes (CLR.W ...). This won't cause an 
obvious problem if your variable is located at an even address. If, however, your 
variable is located at an odd address, an address error is generated. You can prevent 
this from happening by making sure that your variable, say myStyle, is located at an 
even address. In Lisa Pascal, you would do this by allocating two variables as follows: 


VAR 
dummyStyle: Style; {this will be at odd address} 
myStyle:Style; {this will be at even address} 
{rest of declarations go here} 


or, by the equivalent: 


VAR 
myStyle,dummyStyle: Style; {this will allocate...} 
{dummyStyle first, at an odd address} 
{rest of declarations go here} 


DummyStyle is allocated first by the compiler, myStyle second, so that myStyle is on 
an even address. When GetItemStyle does the CLR.W, both myStyle and 
dummyStyle will be cleared, and no address error will be generated. 


To ensure that myStyle is allocated on an even address, declare your variables of type 
Style before declaring any other variables. For every variable of type Style that you 
wish to use, you need to declare two variables of type Style — a dummy variable and 
the one you wish to use. 


Since you can't know at compile time which ROM your program will be executing under, 
you have to use this method any time you wish to call Get ItemStyle. 
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#62: Don't Use Resource Header Application Bytes 
See also: The Resource Manager 


Written by: Bryan Stearns January 23, 1986 


The Resource Manager section in Inside Macintosh which describes the internal format 
of a resource file shows an area of the resource header labeled “Available for 
Application Data". You should not use this area — as it will be used by future versions 
of the Resource Manager. 
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#63: WriteResource Bug Patch 


See also: The Resource Manager 
Technical Note #54—Limit to Size of Resources 
Technical Note #64—IAZNotify Pointer 


Written by: Rick Blair & Jim Friedlander & 
Bryan Stearns January 15, 1986 
Modified by : Jim Friedlander March 3, 1986 


A bug in the 64K ROM limits the size of resources that are written to disk to 
32K. This patch fixes that problem. The March 3 modification was made so 
that the patch runs correctly on Macintosh XLs. 





This patch fixes the problem with an interaction between the trap dispatcher and 
WriteResource that limits the size of resources written using WriteResource to 32K. 
This problem exists only on 64K ROMs, it does not exist on 128K ROMs or on the 
Macintosh XL. As explained in Technical Note #54, the problem is caused by the fact 
that the trap dispatcher does a TST.wW ona handle size, which is a long. To fix the 
problem, we will install a patch to GetHandleSize. The patch acts like the last part of 
the trap dispatcher. Instead of doing a TST.w DO, however, the patch will do a TST.L 
DO before returning to WriteResource. 


To preserve precious space in the system heap, we will only install an absolute JMP 
instruction in the system heap. That gmp will jump to the actual patch, which will be in 
the main segment (so it won't be relocatable) of our program. GetHandleSize Is 
already patched in the system file to fix an odd stack problem, so we have included the 
code for that patch in our patch. 


When your program starts up, call PatchGHs. Before exiting your program, call 
UnPatchGHS. You can either call it from your code, or from your IAZNotify procedure 
(see Technical Note #64). The source of the patch (in Workshop Assembler format) 
follows: 
-NOlist 
. INCLUDE TlAsm/QuickEqu.Text ; standard includes 
. INCLUDE TlAsm/QuickTraps.Text 
. INCLUDE TlAsm/SysEqu.Text 
. INCLUDE TlAsm/SysTraps.Text 
. INCLUDE TlAsm/ToolEqu.Text 
. INCLUDE TlAsm/ToolTraps.Text 
.list 


Technical Note #63 page 1 of3 WriteResource Bug Patch 


ROM85 .EQU S$28E this problem only exists on old ROMS 


s Ea yp m e o lr r ee egy ee i is ee ee ee ee ee ee ee ee ee ee oo oe ee ee a o Á Á o Á l eae eS eee 


; PROCEDURE PatchGHS; EXTERNAL; 


-PROC PatchGHS 
. REF RtnBeg 


TST.L ROM85 
BPL.S Done 
MOVE.L §ROMBASE,A0 
MOVE . B 9(A0), DO 
CMPI.B #SFF,DO 
BEQ.S Done 


MOVE.L #$A025,D0 
_GetTrapAddress 
MOVE.L AQ, -(SP) 
MOVE.L #10,D0 
_NewPtr ,SYS 


MOVE.W #S4EF9, (A0) 
LEA RtnBeg, Al 
MOVE.L  A1,2(A0) 
MOVE.L (SP) +, 6 (A0) 
MOVE.W  #$A025,D0 
_SetTrapAddress 


zsee which ROM we're running on 
don't need the patch in the new ROM 
check for XL 

;get ROMBASE + 9 

;see if XL 

don't need the patch for XL 


jwe’re going to save the old trap address 

;for GetHandleSize 

;puts the old address on the stack 

;6 bytes for jump, 4 bytes for Old address 
allocate space for the JMP 

¿instruction in the system heap (returns 
;pointer in A0) 


;JMP Abs.L instruction 

:get the patch address 

;put patch address in 

;put old address into our heap block 
¿point the patch at our vector (in A0) 


Done RTS 


; PROCEDURE UnPatchGHS; EXTERNAL; 


.PROC UnPatchGHS 


TST.L ROM85 
BPL.S DoneUn 
MOVE.L ROMBASE, AO 
MOVE . B 9(A0),DO0 
CMPI.B #SFF,D0 
BEQ.S DoneUn 


MOVE.W #5A025,D0 
_GetTrapAddress 
MOVE.L 6 (A0), - (SP) 
_DisposPtr 
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s;don't need to unpatch if on new ROMS 


¿check for XL 

;get ROMBASE + 9 

;see if XL 

;don't need the patch for XL 


;get the address of our patch 


¿get old trap address, put on stack 
¿don't leave stuff lying around in system heap 
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MOVE.L (SP)+,A0 ¿get original address for GetHandleSize 
MOVE.W #$A025,D0 
_SetTrapAddress ;set back to original address 


DoneUn 
RTS 


°° o-oo ee ee ee ee es ee es ee ee es es ee ees es ge es es ss cs ee es es ee es es es ees ee es ee ee ee ee ee ee ee ee es es ee ee ee ee eee ee ee ee ee ee ee ee ee ee a a es es es ee ee ee ee ee ee ee 


DEF RtnBeg 
RtnBeg .EQU * 


;the next 5 lines are the old patch to take care of an odd stack problem 


JSR $402CD8 ¿call old GetHandleSize 

CMPI.L #$00404C4C,$1C(SP) ;see if we came from Launch? 

BNE.S @l ;no; no need to round up to an even number 
ADDOQ.L #1,D0 round to even number 

BCLR #0,D0 


jnext we check to make sure that we only change things if we came from the 
;problem-causing instruction in WrRsrc. 


Q1 CMPI.L #$0040DEB4, $1C (SP); see if we came from WrRsrc 


BNE.S @2 jno, we will let the trap dispatcher finish up 
;now we patch in ~-our- version of the tail end of the trap dispatcher 
ADDQ #4, SP ;throw away return address to trap dispatcher 
MOVEM.L  (SP)+,A0-A1 ;restore all registers that dispatcher saved 
MOVEM.L (SP)+,D1-D2/A2 
ADDQ #4, SP throw away status and zero word 
TST.L DO sand I do mean LONG!!!!!!!t! 
@2 RTS sreturn to whoever called GetHandleSize in the 
;lst place 
-END 


Again, make sure that you call UnPatchGHS before exiting your application, or that you 
have an IAZNotify routine that changes the trap address back to what it was before 


you changed it! 
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#64: IAZNotify Pointer 


See also: Memory Manager Programmer's Guide 
Technical Note #63 -- WriteResource Bug Patch 


Written by: Jim Friedlander January 15, 1986 


The IAZNotify routine gives your program a chance to restore system 
globals back to their original values, even if your program is not exited ir ~¢ 
normal way. 3 


if your program changes trap addresses or low-memory globals, changing them back 
before exiting your program is critical. Your program may do this before exiting, but 
what happens if the user interrupts your program with a debugger and then does an 
ExitToShell from the debugger? That wouldn't give your program a chance to ‘clean 
up’. Fortunately, there is a way to make sure that things get set back to normal -- the 
IAZNotify routine. This routine, pointed to by the low-memory global, IAZNotify 
($33C), can be used to reset trap addresses, change low-memory globals back to their 
original states, etc . This routine is called by InitApp1Zone and should be located in 
the main segment of your program. 


Here is a short example of an IAZNotify routine that could be used in conjunction with 
the WriteResource patch of Technical Note #63. 


Given the following variables and constants: 


CONST 
GetHSTrapNum = $25; { in TN #63, we're patching GetHandleSize } 
IAZGlobal = $33C; { location of IAZNotify pointer } 
VAR 
IAZNotifyPtr: *longint; 
oldIAZ: longint; { to save the old value of IAZNotify } 


we can set up the pointer by: 


IAZNotifyPtr:= Pointer (IAZGlobal); 
O1dIAZ:= IAZNotifyPtr”’; {save old value} 
IAZNotify*:= ord(@NotifyRoutine) ; {point it to our routine} 
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and now for the routine: 


PROCEDURE NotifyRoutine; 


Begin {NotifyRoutine} 
UnPatchGHS; 
SetResLoad (TRUE) ; 
IAZNotifyPtr*:= O1dIAZ; {restore to old value} 


End; {NotifyRoutine} . 


Now, if the user enters a debugger and does an Exit ToShell, the IAZNotify routine 
will be called and will change the trap address for Get HandleSize back to what it was 
before we changed it, set ResLoad to TRUE and it will restore the IAZNotify pointer, so 
that the next InitApp1Zone call does not try to run our code again. 
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#65: Macintosh Plus Pinouts 


See also: Macintosh Hardware Manual 
Written by: Mark Baumwell January 27, 1986 
modified by: Mark Baumwell March 20, 1986 





This note gives pinout descriptions for the Macintosh Plus ports and 
Macintosh Plus cables that are different than the Macintosh 128K and 512K 
Personal Computers. 





Below are pinout descriptions for the Macintosh Plus ports and cables that are different 
than the Macintosh 128K and 512K Personal Computers. Note that any unconnected 
pins are omitted. 


Macintosh Port Pinouts 


Macintosh Plus Serial Connectors (Mini DIN-8) 





(Female 

Connector) 

Pin Name Description/Notes 

1 HSKo Output Handshake (from Zilog 8530 DTR pin) 

2 HSKi/External Clock Input Handshake (CTS) or TRxC (depends on 8530 mode) 
3 TxD- Transmit Data line 

4 Ground 

5 RxD- Receive Data line 

6 TxD+ Transmit Data line 

7 Not connected 

8 RxD+ Receive Data line; ground this line to emulate RS232 


Technical Note #65 page 10f3 Macintosh Plus Pinouts 


Macintosh Plus SCSI Connector (DB-25) 





(Female 
Connector) 

Pin 
1 
2 MSG- 
3 V/O- 
4 RST- 
5 ACK- 
6 BSY- 
7 Ground 
8 DBO- 
9 Ground 
10 DB3- 
11 DB5- 
12 DBé- 
13 DB7- 
14 Ground 
15 C/D- 
16 Ground 
17 ATN- 
18 Ground 
19 SEL- 
20 DBP- 
21 DB1- 
22 DB2- 
23 DB4- 
24 Ground 
25 TPWR Not connected 
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Macintosh Plus Cable Pinouts 


Apple System Peripheral-8 Cable (connects Macintosh Plus to ImageWriter II 
and Apple Personal Modem ) 

(Product part number: M0187) 

(Cable assembly part number: 590-0340-A (stamped on cable itself). 


(Male 
Connector) 





R 
OR 


Macintosh Plus Adapter Cable (connects Macintosh Plus DIN-8 to existing 
Macintosh DB-9 cables) 

(Apple part number: M0189) 

(Cable assembly part number: 590-0341-A (stamped on cable itself). 


( DIN-8 ) Name Notes 
+12V 
HSK 
TxD- 
Ground 
RxD- 
TxD+ 
no wire 
RxD+ 
Ground 


Jumpered to DB-9 pin 1 (in DB-9 connector) 


ONOMhWH 
20 ROWUN DES 
P 


Jumpered to DB-9 pin 3 (in DB-9 connector) 
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#66: Determining Which File System is Active 
See also: File Manager (Alpha Draft) 
Written by: Jim Friedlander December 21, 1985 


Under certain circumstances it is necessary to determine which file system is currently 
running, MFS or HFS. To do this, you need to check the low-memory global called 
FSFCBLen (at location $3F6). This global is one word in length (two bytes) and will be 
equal to -1 if MFS is active and some positive number (currently $55) if HFS is active. 
From Pascal, we could check as follows: 


CONST 

FSFCBLen = $3F6; {address of the low-memory global} 
VAR 

HFS >; “integer; 


HFS:= POINTER(FSFCBLen); 
If HFS* > 0 then Begin 
{we're running HFS} 
End 
Else Begin 
{we're running MFS} 
End; 


Once you've determined that you are running under HFS, don't assume that all 
mounted volumes are hierarchical. You can check if a volume is or isn't hierarchical by 
calling PBHGet Vinfo and then checking the directory signature (the iovSigWord field 
of an HParamBlockRec). A directory signature of $D2D7 means you're looking at an 
MFS volume, a signature of $4244 means you're looking at an HFS volume. 
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#67: Finding the 'Blessed Folder’ 


See also: The File Manager (Alpha Draft) 
Technical Note #66 —Determining Which File System is 
Active 
Written by: Jim Friedlander January 18, 1986 





This Technical Note describes how to determine which folder on an FFS 
volume is the ‘blessed folder’, that is, the folder that contains bott. * 3 
System File and the Finder. 





Knowing which folder on an HFS disk contains the System File and Finder can be very 
useful information. Since the ‘blessed folder’ is in the default Poor Man's Search Path, 
it is a good place to put help files and the like. 


Finding the ‘blessed folder’ is quite simple—it is accomplished with a call to 
PBHGetViInfo. First we need to determine if we are running under HFS, and if so, we 
do the following: 


CONST 

FSFCBLen = $3F6; {location of low-memory global FSFCBLen)} 
VAR 

myHPB: HParamBlockRec; {for the PBHGetVInfo call} 

myWDPB: WDPBRec; {for the PBHSetVol call} 


err: OSErr; 
oldVol: integer; 
vName,fName: str255; 


HFS: “integer; {to check to see if we are running HFS} 
HFS:= POINTER(FSFCBLen) ; {point our variable at the low-memory global} 
if HFS* > 0 then Begin {we're running HFS} 

vName:= ''; {initialize this} 


with myHPB do Begin 
ioCompletion:= NIL; 
ioNamePtr:= @vName; {initialize} 
ioVRefNum:= 0; {get for default volume} 
ioVolindex:= 0; {we're not making indexed calls} 
End; {with} 


err:= PBHGetVinfo (@myHPB, FALSE) ; 
if err <> 0 then report ('PBHGetVInfo') 
Else ... 

End {if HFS* > 0} 
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At this point, the dirlD of the blessed folder on the default volume is 
myHPB.ioVFndrinfo[1}. If myHPB.ioVFndrInfo[1] is 0, it means that there was no 
‘blessed folder’ ( including the case where we're looking at an MFS volume ). If 
myHPB.ioVFndriInfo[1] is 2, it means that the System File and Finder are at the root 
level. myHPB.ioVFndriInfo[2} is the dirID of the startup file. 


We could, for example, use the dirlD of the ‘biessed folder’ to create a resource file in 
the ‘blessed folder’. CreateResFile only creates a resource file on the default volume 
in the default directory (if running HFS). Since we have the dirID of the ‘blessed 
folder’, we can call PBHSet Vol to set the default directory to that directory and create a 
resource file in the ‘blessed folder’. First we set up the parameter block for the 


PBHSetVol call: 


with myWDPB do Begin 
ioCompletion:= NIL; 


ioNamePtr:= NIL; {we don't care about the name} 
ioVRefNum:= 0; {default, or whatever you wish} 
ioWDDirID:=myHPB.ioVFndriInfo[1]; {from previous call} 


End; {with myWDPB} 


You can, of course, set the iovRefNum to whatever is appropriate. 


err:= GetVol (NIL, OldVol) ; {save old default} 
err:= PBHSetVol (@myWDPB, FALSE) ; {open WD to blessed folder} 
if err <> 0 then 

ReportErrorAndExit; {or whatever is appropriate} 


CreateResFile (resFileName) ; 
if ResError <> 0 then 
ReportErrorAndExit; {or whatever is appropriate} 


{ now we can do whatever we need to do with our resource 
file that has been created/opened in the ‘blessed folder’ } 
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#68: Searching All Directories on an HFS Volume 


See also: File Manager (Alpha Draft) 
Technical Note #66 —Determining Which File System is 
Active 


Technical Note #67—Finding the ‘Blessed Folder' 
Written by: Jim Friedlander December 23, 1985 


This Technical Note provides a simple algorithm for searching all directories 
on an HFS volume. 


Now that we have a Hierarchical File System, it may be necessary to search the 
hierarchy for files. WARNING: This can be a very time consuming process on a large 
volume. Generally speaking, your application should avoid searching entire volumes, 
relying instead on files being in specific directories (same directory as the application, 
or in the ‘blessed folder’) or on having the user find files with Standard File. 


Under MFS, indexed calls to PBGet FileInfo would return information about all files on 
a given volume. Under HFS, the same technique only returns information about files in 
the current directory. 


The most convenient way to search a tree structure is with a recursive search. The only 
potential problem with a recursive search is that it can use up a lot of stack space. The 
default stack space on the Macintosh is 8k. We therefore have to try to keep the stack 
frame small. This example does that by enclosing the actual recursive routine in a shell 
that can hold most of the variables that we will need. This dramatically reduces the size 
of the stack frame. This example uses only 26 bytes of stack space each time the 
routine recurses. That is, it could search 100 levels deep (pretty unlikely) and only use 
2600 bytes of stack space. 


Please notice that when the routine comes back from recursing, it has to clear the 
non-local variable err, since the reason that the routine came back from recursing is that 
PBGet Cat Info returned an error: 


EnumerateCatalog(myCPB.ioDrDirID); 
err:= 0; {clear error return on way back} 


Please notice also that myCPB.ioDrDirId has to be set each time you call 
PBGetCatInfo. This is because if PRGetCatInfo gets information about a file, it 
returns ioF1Num (the file number) in the same location that the ioDrDirID previously 
occupied. 
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One other thing to watch for is when you check the file attributes bit to see if you've got a 
file or a folder. You need to check bit 4, the fifth Least Significant Bit. Remember, the 
Toolbox bit manipulation routines order the bits in reverse order from standard 68000 
notation. That's why a BitTst (@myCPB.ioFlAttrib, 3) is used. 


And now, here's the routine: 


PROCEDURE EnumerShell (DirIDToSearch: Longint) ; 
VAR 
myCPB: CinfoPBRec; 
err: OSErr; 
myWDPB: WDPBRec; 
TotalFiles,TotalDirectories: integer; 


PROCEDURE EnumerateCatalog(dirIDToSearch: longint); 
VAR 
index: integer; 


Begin {EnumerateCatalog} 
index:= 1; 
repeat 
FName:= ‘'; {nil out name} 
myCPB.ioFDirIndex:= index; 
myCPB.ioDrDirID:= dirIDToSearch; {we need to do this every time through} 


err:= PBGetCatInfo(@myCPB, FALSE); 


If err = noErr then 
if BitTst (@myCPB.ioFlAttrib,3} then Begin (we have a dir} 
TotalDirectories:=TotalDirectories+1; 
EnumerateCatalog(myCPB.ioDrDirID); 
err:= 0; {clear error return on way back} 
End {if BitTst} 
Else Begin{we have a file} 
TotalFPiles:= TotalFiles + 1; 
{here we could call a routine that compares a string with 
myCPB.ioNamePtr”} 
End; {else} 
index:= index + 1; 
until err <> noErr; 
End; {EnumerateCatalog} 


Begin {EnumerShell} 
TotalFiles:= 0; 
TotalDirectories:= 0; 
err:= PBHGet Vol (@myWDPB, FALSE) ; {get the default volume} 


with MyCPB do Begin 
iocompletion:= Nil; 
ioNamePtr:= @FName; 
ioVRefNum:= myWDPB.ioVRefNum; {for now, default vol, set this to what you want} 


End; {with} 
EnumerateCatalog(2);{DirID 2, the root level} 
End; {EnumerShell} 


Please make sure that you are running under HFS before you use this routine! You can 
do partial searches of a volume by specifying a starting DirId other than 2, which 
represents the root level. Enjoy!! 
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#69: Setting ioFDirlndex in PBGetCatinfo Calls 


See also: The File Manager (Alpha Draft) 
Technical Note #24—Available Volumes and Files 
Technical Note #66—Determining Which File System is 
Active 
Technical Note #67—Finding the ‘Blessed Folder’ 


Written by: Jim Friedlander February 15, 1986 


This Technical Note describes how to set ioFDirIndex when calling 
PBGetCat Info. 


The Alpha Draft of The File Manager is not very specific in describing how to use 
ioFDirIndex when calling PBGetCatInfo. It correctly says that ioFDirIndex should 
be positive if you are making indexed calls to PBGetCat Info (analagous to making 
indexed calls to PBGet VInfo as described in Technical Note #24). However, the 
statement "If ioFDiriIndex is negative or 0, the File Manager returns information about 
the file having the name in ioNamePtr..." is not specific enough. 


If ioFDirIndex is 0, you will get information about files or directories, depending on 
what is specified by ioNamePtr%. 


If ioFDirIndex is -1, you will get information about directories only. The name in 
ioNamePtr^ is ignored. 


For example, given the following tree structure (with sample DirIDs for the directories): 


Root 
(23) Sys f3)MyFiles2 


a [) [) [} SubFiles 


System Finder Filel File2 | 


D 


File3 
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ilin 
We will now make calls to PBGetCat Info of the form: 
err:= PBGetCatinfo (@myCInfoPBRec, FALSE) ; 


Note: We will assume that we just have a WDRefnum and a file name—the information 
that SFGetFile returns. 


Setting up the parameter block 


We will use the following fields in the parameter block. Before the call, ioCompletion 
will always be set to NIL, ioNamePtr will always point at a str255, ioVRefNum will 
always contain a WDRefNum that references the directory ‘SubFiles', and offset 48 
(dirID/£1Num) will always contain a zero: 


Offset in 
parameter block Variable name(s) 
12 ioCompletion 
18 ioNamePtr 
22 iovRefNum 
28 joFDirIndex 
48 ioDirID/ioFLNun/ioDdrDirID 
100 ioDrParID/ioFlParID 
mpl lis t 


The first example will call PBGetCatInfo for the file 'File3'—we will get information 
about the file (ioFDirIndex = 0): 


Before the call After the call 
ioNamePtr”’: 'File3' ioNamePtr^: 'File3' 
ioFDirIndex: 0 Offset 48(ioFLNum): a file number 


Offset 100(parID): 57 


Now we will get information about the directory that is specified by the iovRefNum 
(ioFDirIndex =-1). Notice that ioNamePtr~ is ignored: 


Before the call After the call 
ioNamePtr*: ignored ioNamePtr“%: ‘SubFiles’ 
ioFDirIndex: -1 Offset 48(dirIpD): 57 


Offset 100 (parID): 37 
Notice that, since ioNamePtr® is ignored, Offset 48 contains the dir1ID of the directory 
specified by the iovRefNum that we passed in and that Offset 100 contains the parent 
ID of that directory. 
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Notice that if we try to get information about the directory ‘SubFiles’ by calling 
PBGetCat Info with ioFDirIndex set to 0, we will get an error -43 back (File not found 
error) because there is neither a file nor a directory with the name ‘SubFiles’ in the 
directory that iovRefNum refers to. 


lf you specify a full pathname in ioNamePtr%, then the call returns information about 
that path, whether it is a directory or a file. The iovRefNum is ignored: 


Before the call After the call 
ioNamePtr*: "Root:Sys' ioNamePtr^: 'Root:Sys' 
ioFDirIndex: 0 Offset 48(dirID): 17 
ioVRefNum: refers to 'SubFiles’ Offset 100 (pariID): 2 

Or, if the full pathname specifies a file, the iovRefNum İS overridden: i 
Before the call After the call 
ioNamePtr^: 'Root:Sys:Finder' ioNamePtr^: 'Root:Sys:Finder' 
ioFDirIndex: 0 Offset 48(f1Num): fileNumber 
iovRefNum: refers to ‘SubFiles’ Offset 100 (parID): 17 


Or, given an iovRefNum that refers to 'MyFiles2' and a partial pathname in 
ioNamePtr^, we'll get information about the directory ‘SubFiles’: 


Before the call After the call 

ioNamePtr*: ‘SubFiles' ioNamePtr”: ‘SubFiles’ 
ioFDirIndex: 0 Offset 48(dirIpD): 57 
ioVRefNum: refers to 'MyFiles2' Offset 100 (parID): 37 


PBGetCatinfo and The Poor Man's Search Path (PMSP) 


if no ioDirID is specified (ioDirID is set to zero), calls to PBGet Cat Info will return 
information about a file in the specified directory, but, if no such file is found, will 
continue searching down the Poor Man's Search Path. Note: the PMSP is not used if 
ioFDiriIndex is non-zero ( either -1 or >0). The default PMSP includes the directory 
specified by iovRefNun (or, if iovRefNum is 0, the default directory) and the directory 
that contains the System File and the Finder—the ‘blessed folder’. So for example: 


Before the call After the call 
ioNamePtr’: ‘System’ ioNamePtr’: ‘System’ 
ioFDirIndex: 0 Offset 48(ioFLNum): a file number 


Offset 100 (parID): 17 


You must be careful when using PBGet Cat Info in this way to make sure that the file 
you're getting information about is in the directory that you think it is, and not ina 
directory further down the Poor Man's Search Path. Of course, this does not present a 
problem if you are using the f£Name and the vRefNun that SFGetFile returns. 
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if you want to specifically look at a file in the ‘blessed folder’, please use the technique 
described in Technical Note #67 to get the dirID of the ‘blessed folder and then use 
that dirID as input in the ioDirID field of the parameter block (offset 48). 


ummar j = 0 in all the following): 
lf ioFDirIndex is set to 0: 

1) Information will be returned about files. 

2) Information will be returned about directories as follows: 
A) If a partial pathname is specified by ioNamePtr%* 
then the volume and directory will be taken from 
ioVRefNum. 
B} if a full pathname is specified by ioNamePtr^. In 
this case, ioVRefNum is ignored. 


lf ioFDirIndex is set to -1: 
1) Only information about directories will be returned. 
2) The name pointed to by ioNamePtr is ignored. 
3) If DirID and iovRefNum are Q, you'll get information about 
the default directory. 
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#70: Forcing Sony Disks to be Either 400K or 800K 


See also: Disk Driver 
Disk initialization Package 


Written by: Rick Blair February 13, 1986 


This document explains how to force HFS to initialize a Sony disk as either 
single- or double-sided. The example is written in Lisa Pascal. It only applies 
to the 800K drives, of course. 


You can call the Sony driver to initialize a disk and determine programmatically whether 
it should be initialized as single- (MFS) or double- (HFS) sided. All you have to do is 
call the .SONY driver directly to do the formatting then the Disk Initialization Package to 
write the directory information. 


NOTE: This is not the way you should normally format disks within an application. If the 
user puts in an unformatted disk, you should let her or him decide whether it becomes 
single- or double-sided via the Disk Initialization dialog. This automatically happens 
when you call DIBadMount or the user inserts a disk while in Standard File. The intent 
of this technote is to provide a means for very specific applications to produce, say, 
400K disks. An example might be a production disk copying program. 


Note: 128K ROMs or the Hard Disk 20 file are required for the double-sided drives. 


VAR 
error: OSETII? 
IPtr: “INTEGER; 


ParamBlock: ParamBlockRec; {needs OSIntf} 


WITH ParamBlock do 


BEGIN 
ioRefNum:=-5; {.SONY driver} 
ioVRefNum:=1; {for internal -- 2 for external drive} 
csCode:=6; {Format control code} 
ioCompletion:=Nil; 
IPtr:=@csParam; {point to it;pretend it's an INTEGER} 
IPtr^:=1; {for single-sided, 2 for double-sided} 


error:=PBControl (ParamBlock, TRUE) ; 
IF error=ControlErr THEN 


{you are under MFS which doesn't support control code 6, but it 
would always get formatted single-sided anyway. } 


Technical Note #70 page 1 of2 Forcing Sony Disks to be Either 400K or 800K 


{Other errors are possible: ioErr, etc.} 
END; 


You then cail DlZero in the Disk Initialization Package to write a standard (MFS or HFS) 
directory. It will produce an MFS disk if you formatted it single-sided, and an HFS disk if 
you formatted it as an 800K drive. 
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#71: Finding Drivers in the Unit Table 
see also: Device Manager 


Written by: Rick Blair February 4, 1986 





This note will explain how high-level code can be written to determine the 
driver reference number of a previously installed driver when only the name 
is known. 





You should already be familiar with the Device Manager Chapter of Inside Macintosh 
before reading this technical note. 


The Lisa Pasca! code at the end of this note demonstrates how to obtain the reference 
number of a driver that has been installed in the Unit Table. You substitute the name of 
your driver for the ".YourDriver" string below. 


The reference number may then be used in subsequent calls to the Device Manager 
such aS Open, Control and_ Prime. Disk drivers, for instance, may respond to 
Format Control calls. If the reference number of the disk driver is -12 you can format 
the disk in drive #3 like this: 


WITH ParamBlock do 
BEGIN 
ioRefNum:=-12; 
ioVRefNum:=3; {drive} 
csCode:=6; {Format} 
ioCompletion:=Nil; 
error:=PBControl (ParamBlock, TRUE) 
END; 


The code sample below demonstrates how to obtain the reference number. 
One thing to note is that GRAMBased really only tells you whether DCt1Driver isa 


pointer or a handle, not necessarily whether the driver is in ROM or RAM. SCSI drivers, 
for instance, are in RAM but not relocatable; their DCE entries contain pointers to them. 


CONST 


UTableBase=511¢C; {low memory globals} 

OnitNtryCnt=$1D2; 

GRAMBased=6; {bit in dCtlFlags that indicates whether ROM/RAM) 
drvrName=$12; {length byte and name of driver [string] } 
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VAR 


negcount: INTEGER; 

UBase: “LONGINT; 

UNtryCnt: “INTEGER; 

driveptr: Ptr}; 

h: Handle; 

DCEH: DCt lHandle; 

myUnit: UnitPtr; 

Ss; Str255; 

BEGIN 

UBase:=Pointer (UTableBase) ; {point to pointer to unit table} 
UNtryCnt:=Pointer({UnitNtryCnt); {point to word with unit table count} 
negcount:= -UNtryCnt*%; {get -(table size) } 


{check to see that driver is installed, obtain refnum. 
This assumes that an Open was done previously -- probably by an INIT. 
It doesn't have to be open now, though.} 


drvrrefnum:=-1l; {we'll start with unit #11 (driver refnum = -12)--right after .ATP entry } 
myUnit:=Pointer (UBase*+44) ; {start at unit 11 (4 bytes per slot) } 


{Here's the loop which looks through the unit table until it finds the driver or reaches the 
end} 


REPEAT 
drvrrefnum:= drvrrefnum-1; {bump to next refnum} 
DCEH:=myUnit*; {handle to Device Control Entry} 


myUnit:=Pointer (Ord4 (myUnit)+4); {point myUnit to handle for next time) 


IF DCEH=NIL THEN s;:='' {skip it if it's an empty slot) 
ELSE 
WITH DCEH^^ DO {this is safe -- no chance of block moving before 


the dCtlFlags or dCtlDriver references} 
BEGIN 
IF BTST(dCtlFlags,dRAMBased) THEN 
{If it's a RAM driver} 


BEGIN 

h:=Bandle(dCtiDriver) ; {we know it's a handle since it's a RAM driver} 
driveptr:=h* {zee deréference} 

END 

ELSE 


driveptr:=Ptr(dCtlDriver); {a pointer for "ROM" drivers} 


IF driveptr<>NIL THEN {if it hasn't been purged} 
BEGIN 
s:=StringPtr (ORD4 (driveptr)+tdrvrName)*; {name of driver} 
UprString({s,FALSE) {force same case for compare} 
END 


END; {WITH} 


UNTIL ({s='.YOURDRIVER') OR (drvrrefnum=negcount) ; 
{we loop until we find it or we've just looked at the last sliot in UTable} 


IF s<>'’. YOURDRIVER' THEN {Can't find driver} 
{do whatever for the "not found" case} 


That's all there is to locating a driver and picking up the reference number. 
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#72: Optimizing for the LaserWriter - Techniques 


See also: The Print Manager 
QuickDraw 
TextEdit 
AppleTalk 
Technote #41: Drawing Into an Offscreen Bitmap 
PostScript Language Reference Manual, Adobe Systc. æ 
PostScript Language Tutorial and Cookbook, Advwe 

Systems 


Written by: Ginger Jernigan February 3, 1986 





This Technical Note describes techniques for optimizing your code for 
printing on the LaserWriter. 





Although the Print Manager was originally designed to allow application code to be 
printer independent, there are some things about the LaserWriter that in some cases 
have to be addressed in a printer dependent way. This technote describes what the 
LaserWriter can and can't do, memory considerations, speed considerations, as well as 
other things you need to watch out for if you want to make your printing more efficient on 
the LaserWriter. 


How To Determine Which Printer Is Currently Selected 


In most instances, you will not need to know which printer the user has selected. Most of 
the techniques outlined here apply mostly to your overall program design, and, 
therefore, work for both the ImageWriter and the LaserWriter. However, when there is a 
need to know, here is the method you should use: 


If you are using the Print Manager, first call Prvalidate to make sure you have the 
correct print record. Look at the high byte of the wdev word in the Prst1 subrecord of 
the print record. The value will be 1 if the current printer is an ImageWriter and 3 if it is a 
LaserWriter. (Note: If you have your own driver and want to have your own number, 
please let us know and we'll register it.) 


Using QuickDraw With the LaserWriter 


When you print to the LaserWriter, all of the QuickDraw calls you make are translated 
via QuickDraw bottlenecks, into PostScript, the language that the LaserWriter has in 
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ROM. Most of the operations available in QuickDraw are available in PostScript with a 
few exceptions. Here is what the LaserWriter driver supports: 


¢ Alltransfer modes are available except XOR and Not XOR. 
e The grafverb invert is not supported. 


e Calling SetOrigin within the PrOpenPage and PrClosePage Calls for the 1.0 
LaserWriter driver is not supported. Use OffsetRect instead. It is supported in the 
3.0 LaserWriter driver. 


e Regions are not supported. They are ignored. You can simulate regions using 
polygons or bitmaps. Take a look at Technote #41, Drawing Into An Offscreen Bitmap 
for how to create offscreen bitmaps. 


e Clip regions should be limited to rectangles. 


e There is a small difference in character widths between screen fonts and printer 
fonts. Only the endpoints of the text strings will be the same. See the discussion 
below What You See Is Not Always What You Get. 


What You See Is Not Always What You Get 


Unfortunately, what you see on the screen is not always what you get. If you are using 
standard graphical objects, like rectangles, circles, etc., the object will be the same size 
on the LaserWriter as it is on the screen. There are, however, two types of objects where 
this is not the case: text and bitmaps. 


As stated above, there is a difference between the widths of characters on the screen 
and the widths of characters on the printer because of the difference in resolution. 
However, to maintain the integrity of line breaks, the LaserWriter driver will change the 
word spacing and the character spacing to maintain the endpoints of the lines as 
specified (see below). What this all means is that you can't count on the positions or the 
widths of printed characters being exactly the same as they are on the screen. That's 
why in MacDraw, for example, if you carefully place text in a rectangle and print it, 
sometimes the text extends beyond the bounds of the rectangle. 


The exception to this is if you are running on the 128K ROMs. The new Font Manager 
supports the specification of fractional pixel widths for screen fonts, increasing the 
screen to printer accuracy. On the Macintosh Plus this fractional width feature is turned 
off. To enable it you can set a low memory global, fractEnable, at $BF4, after you call 
InitFonts. 


You can use picComments to left, right, or center justify text. Only the left, right, or center 
endpoints will be accurate. If the text is fully justified, both endpoints will be accurate. 
These picComments will be discussed in another technote. 


Bitmaps are another problem. The ratio of the printer resolution to the screen resolution 
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is 4.17. Not quite four times. In order to print bitmaps on the LaserWriter, they are scaled 
four times. It's a little rough doing 4.17. The problem this creates, though, is that the 
bitmap is a little smaller when it is printed then it is on the screen. There's no way to get 
around this. 


Memory Considerations 


In order to print on the LaserWriter, you need to make sure that you have enough 
memory available to load the LaserWriter driver's code. The best way to do this is to 
have all the code you need for printing in a separate segment and unload everything 
else. When you print on the LaserWriter you are only able to print in Draft mode. You 
will not be able to spool, as the ImageWriter does in the standard or high quality 
settings, and your print code, data and the driver code will have to be resident in 
memory. In terms of memory requirements, you will need to have from 15 to 20 K 
available for the 1.0 LaserWriter software and AppleTalk, and more for the 3.0 
LaserWriter and AppleTalk, every time you print. 


Printable Paper Area 


On the LaserWriter there is a 0.45 inch border that surrounds the printable area of the 
paper (this is assuming an 8.5" x 11" paper). This is different than the available print 
area of the ImageWriter. The reason you cannot print a larger area is because 
PostScript takes the available amount of memory in the printer and centers it on the 
paper. We don't have enough RAM in the LaserWriter to image the entire sheet of 
paper. 


Speed Considerations 


Although the LaserWriter is pretty speedy as it is, there are some things you can do in 
your code that will make sure it remains speedy. 


e Try to avoid using any of the QuickDraw Erase calls (i.e. EraseRect, EraseOval, 
etc.). It takes a lot of time to handle the erase function because every bit (90,000 
bits/sq. in.) has to be cleared. Erasing is unnecessary because the paper does not 
need to be erased the way the screen does. 


* Printing patterns takes time, since the bitmap for the pattern has to be built. The 
patterns Black, White, and all the Grays have been optimized for the LaserWriter to 
use the PostScript gray scales. If you use a different pattern, it works but just takes 
longer than usual. Also, on the 1.0 LaserWriter driver patterns are NOT rotated. On 
the 3.0 LaserWriter driver they are. 


e Try to avoid changing fonts frequently. PostScript has to build each character it need 
by either using the drawing commands for the built-in fonts (Times, Helvetica, etc.) or 
by resizing bitmaps downloaded from screen fonts from the Macintosh. As each 
character is built it is cached if there's room, so if that character is needed again 
PostScript gets if from the cache. When the font changes, the characters have to be 
built from scratch in the new font. This takes time. Also, if the font isn't in the 
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LaserWriter, time is taken in downloading it from the Macintosh. If the user has the 
option of choosing fonts, you have no control over that. However, if you are the one 
controlling which fonts to use, keep this in mind. 


e Avoid using TextBox. It makes calls to EraseRect for every line of text it draws. The 
calls to EraseRect slow the printer down. You might want to use a different method 
of displaying text (like DrawString Of DrawText) or write your own version of 
TextBox. If you are making TextBox Calls now, switching to something else can 
improve your speed on the order of 5 to 1. 


e Because of the way rectangle intersections are determined, if your clipRect falls 
outside of the rPage rectangle, you will slow down the printer substantially. By 
making sure your clipRect is entirely within the rPage rectangle, you can get a 
speed improvement of approximately 4 to 1. 


¢ Do not use spool-a-page/print-a-page as some applications do when printing on the 
ImageWriter. it will slow things down considerably because of all of the preparation 
that has to be done when a job is initiated. See the discussion of 
Spool-a-Page/Print-a-Page below. 


e Using DrawChar to place every character you're printing can take tons of time. One 
reason, of course, is because it has to go through the bottlenecks for every character 
that is drawn. The other is that the printer driver does its best to do line layout, making 
the character spacing just right. If you're trying to position characters and the driver is 
trying to position characters too, there is conflict and printing takes much longer than 
it needs to. In the 3.0 LaserWriter driver there are picture comments that turn off the 
line layout optimization, alleviating some of the problem. However, shying away from 
this method of printing is strongly recommended. 


Clipping Within Text Strings 


When clipping characters out of a string, make sure that the clipping rectangle or region 
is greater than the bounding box of the text you want to clip. The reason is that if you clip 
part of a character, like you clip off a descender, the clipped character will have to be 
rebuilt (see above). This takes time. Actually, because of the difference between screen 
fonts and printer fonts, chances are that you will not be able to accurately clip the right 
characters unless you are running on the 128K ROMs and have fractional pixel widths 
turned on. 


When to Validate the Print Record 


To validate the print record, call Prvalidate. You need validation to check to see if all 
of the fields are accurate according to the current printer selected and the current 
version of the driver. You should call Prvalidate when your application starts and 
you've allocated a new print record, or whenever you need to access information from 
the print record (like when you get rPage). The routines PrSt1Dialog and 
PrJobDialog do call Prvalidate when they are called, so you don't have to worry 
about it then. 
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Spool-a-Page/Print-a-Page 


Many applications, when printing to the ImageWriter, will use the approach of spool a 
page, then print a page, in order to get around problems with limited disk space. As 
noted above under Memory Considerations, there is no spooling when printing to the 
LaserWriter. In order to optimize for the LaserWriter you may want to consider having 
two print loops. One would be for spool-a-page/print-a-page for the ImageWriter. The 
other would be for printing without spooling for the LaserWriter. 


Empty QuickDraw Objects 


QuickDraw objects that are empty (meaning they have no pixels in them) and are filled 
but not framed, will not print on the ImageWriter and will not show up on the screen. On 
the LaserWriter, however, they are real objects and will be printed. 


Cancelling or Pausing the Printing Process 


If you install a procedure for handling requests to cancel printing, with the option of 
pausing the printing process, beware of timeout problems. Communication between the 
Macintosh and the LaserWriter has to be maintained. If there is no communication for a 
period of time (up to two minutes), the printer will timeout and the print job will be 
terminated. You may want to disable your Pause button while printing to the 
LaserWriter, enabling it for the ImageWriter. 


Chooser Desk Accessory 


With the Choose Printer or Chooser desk accessories, the user can change the printer 
while in the application. If for some reason you do not want the user to choose printers 
you can disable the Chooser. If you clear bit 7 of the low memory byte $946, the 
Chooser will not allow the user to change printers. Setting the bit will enable the 
Chooser. If you do disable the Chooser, don't forget to enable it before 
leaving your program. Otherwise the Chooser will be disabled until the Macintosh is 
rebooted. 


Error Messages 


The errors below are reported by the Print Manager only. If an error occurs that does not 
belong to the Print Manager, it will put the error in low memory (retrievable by PrError) 
and terminate printing if necessary. 


If you encounter an error inthe middle of a print loop, do not jump out. Just fall through 
and let the Print Manager terminate properly. For example: if you get an error when 
calling PrOpenDoc, make sure you Call PrCloseDoc before exiting. If you get an error 
on PrOpenPage, make Sure you Call PrClosePage and PrCloseDoc before exiting the 
Print loop. Otherwise you will be causing al! sorts of problems. 
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Error Values Constant Description 


0 noErr No error 

128 iPrAbort Abort the printing process (Command-period) 
-1 iPrSavePFil Problem saving print file 

-17 Un-implemented control instruction 

-27 ilOAbort I/O problems 

-108 iMemFullErr Not enough heap space 


The following errors are LaserWriter specific: 


-4101 Printer not found or closed 

-4100 Connection just closed 

-4099 Write request too big 

-4098 Request already active 

-4097 Bad connection refnum 

-4096 No free CCBs (Connect Control Blocks) available 


Of these the most common error encountered will be the -4101 error. This error is 
generated if the LaserWriter is installed but one is not selected. Since this is very 
common it might be a good idea to put up an alert asking the user to open the Chooser 
and select a printer when this error is encountered. 


You may also encounter AppleTalk errors. For a list of these see the AppleTalk section 
of Inside Macintosh. 


These tidbits of information should help you write faster more efficient LaserWriter code. 
Stay tuned for more technotes in the series Optimizing for the LaserWriter. 
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Macintosh Technical Notes € 


#73: Color Printing 
See also: QuickDraw 


Written by: Ginger Jernigan February 3, 1986 





This Technical Note discusses the implementation of color printing _ 2 
Macintosh application. ay 





Color is an all but forgotten feature of the Macintosh system. It has remained virtually 
unused by applications mainly because of the lack of color output devices. Earlier in 
1985 Apple began shipping the ImageWriter Il. In addition to many other features, the 
ImageWriter Il is capable of generating color. The ribbon has black, blue, red and 
yellow. This was great except for the fact that the ImageWriter driver for the Macintosh 
could not generate color. 


This limitation of the ImageWriter driver has been solved (sort of). The 2.1 version of the 
ImageWriter and AppleTalk ImageWriter drivers do in fact generate the proper codes for 
the generation of color on the ImageWriter II. The purpose of this technote is to briefly 
describe how to add color to your application and to outline the features that the new 
drivers support. 


The ImageWriter driver is capable of generating each of the eight standard colors 
defined in QuickDraw by the following constants: 


whiteColor 
blackColor 
redColor 
greenColor 
blueColor 
cyanColor 
magentaColor 
yellowColor 


To generate color all you need to do is set the foreground and background colors 
before you begin drawing (initially they are set to blackColor foreground and whiteColor 
background). To do this you call the QuickDraw routines ForeColor and BackColor as 
described in Inside Macintosh. lf you are using QuickDraw pictures, make sure you set 
the foreground and background colors before you call ClosePicture So that they are 
recorded in the picture. Setting the colors before calling DrawPicture doesnt work. 
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The drivers also recognize two of the transfer modes: srcCopy and srcoOr. The effect of 
the other transfer modes is not well defined and has not been tested. It may be best to 
stay away from them. 


Caveats 


You may have realized that this color capability of the ImageWriter driver has not been 
announced. The reason is simple: The color capabilities of the ImageWriter driver were 
a late addition to the code and have not been tested. Although we feel very comfortable 
with it, if you use it you are on your own. 


When printing a large area of more than one color you will encounter a problem with the 
ribbon. When you print a large area of one color, the printer's pins pick up the color from 
the back of the ribbon. When another large area of color is printed, the pins deposit the 
previous color onto the back of the ribbon. Eventually the first color will come through to 
the front of the ribbon, contaminating the second color. You can get the same kind of 
effect if you set, for example, a foreground color of yellow and a background color of 
blue. The ribbon will pick up the blue as it tries to print yellow on top of it. This problem 
is partially alleviated in the 2.3 version of the ImageWriter driver by using a different 
printing technique. 


The ribbon goes through the printer rather quickly when printing large areas. When the 
ribbon comes through the second time the colors don't look too great. 
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#74: Don't Use the Resource Fork for Data 


See also: Inside Macintosh: The Resource Manager 
Technica! Note #62 — Resource Header Application Bytes 


Written by: Bryan Stearns March 13, 1986 





Do not use the resource fork of a file for non-resource data. Parts of the system 
(including the File Manager and the Finder) assume that if this fork exists, it will contain 
valid Resource Manager information. 


OpenRF was provided to allow copying of the resource fork of a file in its entirety, without 
Resource Manager interpretation. Do not use it to open "another data fork". 


The File Manager assumes that the first block of the resource fork of a file will be part of 
the resource header, and puts information there to aid in scavenging. Note that this 
means that if you copy a resource file (opened with OpenRF), the duplicate may not be 
exactly like the original. 
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Macintosh Technical Notes C3 


#75: The Installer and Scripts 
See also: The Resource Manager 


Written by: scott Douglass March 14, 1986 


This technote describes the Installer, version 2.1, and how to create your 
own scripts. 


Overview 

The Installer is a general purpose program that is designed to install, update and 
remove Macintosh™ software. It can copy and delete both files, and resources within 
files. The Installer is controlled by “scripts” which are resources that contain lists of 
files and resources along with other information. The scripts are located either in the 
files being copied or in separate script files. Scripts are resources of type 'insc’ with 
any id, commonly 0. The Installer looks in files on the same disk as the Installer of 
type 'PRES', 'PRER', 'RDEV' and ‘uins' and uses the first 'insc' resource it finds in 
each file. On HFS volumes the Installer looks in only the root, the System Folder, the 
Installer’s parent folder and the immediate descendants of the Installers parent 
folder for files with scripts in them. 


Why? 

There are many instances when simply copying a file from one disk to another is not 
sufficient to install a piece of software. Typically resources must be copied into the 
System File at the same time. A good example of this is the LaserWriter™ driver; it 
must have the AppleTalk drivers installed in order to run on 64K ROM machines. 
Although this is the recommended method of installing into the System File, it is 
strongly recommended that nothing be kept in the System File unless absolutely 
necessary. 


The Scripts 

A script is a list of instructions for the Installer. The instructions are for the most part. 
highly encoded. A script can specify that files or resources be copied from a “source” 
disk (the disk that the Installer application is on) to a “target” disk that the user 
chooses. Scripts can be made either directly using the Resource Editor or from a text 
file using RMaker. A pictorial representation of a script is shown below (see Figure 
1); it deserves some explanation. The numbers in parenthesis are the length of each 
field in bytes. A Script consists of the following fields: Format, Script Flags, Script 
Name, Script Help, Files List, Resource Files List and Disk Blocks List. 
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Script: 


Resource File List 
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Figure 1. 


Script Format 

The Script Format field (2 bytes) is an unsigned integer indicating the script 
format number. It is currently zero. If the Installer encounters a script with a 
format higher than it knows how to handle the script will be ignored. 
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Script Flags 
The Script Flags field (2 bytes) is 16 bit-flags that are currently unused and 
should be specified as zero. 


Script Name 

The Script Name field is an even-padded Pascal string! that the Installer displays 
to the user to be selected. By convention it includes the version number of the 
software being installed. 


Script Help 
The Script Help field is an even-padded word-counted string? that the Installer 
displays if the script is selected when Help is clicked. 


File List 
The File List field specifies the files that are to be copied or deleted. It consists of 
a Number of Files field followed by zero or more File Spec fields. 


Number of Files 
The Number of Files field (2 bytes) is an unsigned integer specifying how 
many File Spec fields follow it. 


File Spec 

A File Spec field specifies a file to be deleted or copied. It consists of the 
following fields: File Spec Flags, File Type, File Creator, Creation Date, 
Handle, FDelsize, FAddsize and File Name. 


File Spec Fiags 
The File Spec Flags field (2 bytes) is 16 bit-flags that specify whether a file 
is to be copied or deleted. The bits are as follows (see Figure 2): 
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bitO: 1, indicating that this is a file spec. 

bit 1: type and creator; if this bit is 1 then the source file’s type and 
creator must match the file spec’s File Type and File Creator fields 
and any existing target file’s type and creator must also match if no 
old type and creator (bit 7) is 0. 
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bit2: creation date; if this bit is 1 the source file’s creation date must 
match the file spec’s Creation Date field. 

bit3: need not exist; if this bit is 1 then the file need not exist on the 
source disk. If the file does not exist then the file spec will be 
ignored. 

bit 4: data fork; if this bit is 1 then the data fork of the file will be copied or 
deleted. 

bit5: resource fork; if this bit is 1 then the resource fork of the file is 
copied or deleted. 

bit 6: update only; if this bit is 1 and the target file does not exist then the 
source file will not be copied to the target disk even if copy (bit 13) 
is 1. 

bit 7: no old type and creator; the type and creator of the target file need 
not match the type and creator fields even if type and creator (bit 1) 
is 1. 

bit 8: search for file; the source and target files need not be in the 
System Folder (applies only to HFS disks). 

bits 9-12: reserved; should be specified as 0. 

bit 13: copy; if this bit is 1 and the user clicks Install then the source file 
will be copied to the target disk. The file must exist on the source 
disk unless need not exist (bit 3) is 1. 

bit 14: delinst; if this bit is 1 and the target file exists and the user clicks 
Install then the target file will be deleted (before the source file is 
copied). If the file does not exist on the target disk then this bit will 
be ignored. 

bit 15: delrmve; if this bit is 1 and the target file exists and the user clicks 
Remove then the target file will be deleted. If the file does not exist 
on the target disk then this bit will be ignored. 


File Type 

The File Type field (4 bytes) specifies what the source and target files’ 
types are expected to be. If type and creator (bit 1) is O then this field is 
ignored. If no old type and creator (bit 7) is 1 then the target file's type 
does not have to match. This field is to help insure that the correct file is 
being installed or removed. 


File Creator 

The File Creator field (4 bytes) specifies what the source and target files’ 
creators are expected to be. If type and creator (bit 1) is 0 then this field is 
ignored. If no old type and creator (bit 7) is 1 then the target file's creator 
does not have to match. This field is to help insure that the correct file is 
being installed or removed. 


Creation Date 

The Creation Date field (4 bytes) specifies what the source file’s creation 
date is expected to be. If creation date (bit 2) is O then this field will be 
ignored. This field is to help insure that the correct file is being installed. 
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Handle, FDelsize and FAddsize 
The Handie, FDelsize and FAddsize fields (4 ae each) are used 
internally and should be specified as zero. 


File Name 
The File Name field is an even-padded Pascal string that specifies the 
source and target file names. 


Resource File List 

The Resource File List field specifies the resources that will be copied or deleted. 
It consists of a Number of Target Files field followed by zero or more Target File 
Spec and Source File List fields. 


Number of Target Files 
The Number of Target Files field (2 bytes) is an unsigned integer specifing 
how many Target File Spec and Source File List fields follow it. 


Target File Spec 
The Target File Spec field is a File Spec that specifies the file on the target 
disk that resources are to be copied into or deleted from. 


Source File List 

The Source File List field specifies files from which resources will be copied. 
It consists of a Number of Source Files field followed by zero or more Source 
File Spec and Resource List fields. 


Number of Source Files 

The Number of Source Files field (2 bytes) is an unsigned integer 
specifing how many Source File Spec and Resource Files List fields 
follow it. 


Source File Spec 
The Source File Spec field is a File Spec that specifies the file on the 
source disk from which resources will be copied. 


Resource List 
The Resource List field specifies a list of resources that are to be copied 
from the source file to the target file or deleted from the target file. 


Number of Resources 
The Number of Resources field (2 bytes) is an unsigned integer specifing 
how many Resource Spec fields follow it. 


Resource Spec 

A Resource Spec field consists of the following fields: Resource Spec 
Flags, Resource Type, Source ID, Target ID, CRC/Version, Fillert, Filler2, 
FDelsize, FAddsize, Resource Name and Previous CRC List. 
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Resource Spec Fiags 

The Resource Spec Flags field (2 bytes) is 16 bit-flags that specify 
whether a resource is to be copied or deleted. Bits 3, 6, 7, 13, 14 and 
15 have similar definitions to the same bits in the File Spec Flags. 
The bits are as follows (see Figure 3): 
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bit O: 0, indicating that this is a resource spec 

bit 1: find by id; if this bit is 1 then the resource will be found in the 
source file by using the id in the id field, otherwise it will be found 
using the Resource Name field. 

bit2: reserved; should be specified as 0. 

bit 3: need not exist; if this bit is 1 then the resource need not exist on the 
source disk. If the resource does not exist then the resource spec 
will be ignored. 

bit 4: even if protected; if this bit is 1 then the resource will be deleted 
from the target file (if delinst (bit 14) or delrmve (bit 15) is 1) even if 
it is protected in the target file. 

bit 5: reserved; should be specified as 0. 

bit 6: update only; if this bit is 1 and the resource does not exist in the 
target file then the resource will not be copied to the target file even 
if copy (bit 13) is 1. 

bit 7: no old name; the name of the resource in the target file need not 
match the name in the Resource Name field this applies only if find 
by id is 1. 

bits 8-12: reserved; should be specified as 0 

bit 13: copy; if this bit is 1 and the user clicks Install then the resource in 
the source file will be copied to the target file. The resource must. 
exist in the source file if need not exist (bit 3) is 0. 

bit 14: delinst; if this bit is 1 and the resource exists in the target file and 
the user clicks Install then the resource will be deleted from the 
target file (before the resource is copied from the source file). If the 
resource does not exist in the target file then this bit will be ignored. 

bit 15: delrmve; if this bit is 1 and the resource exists in the target file and 
the user clicks Remove then the resource will be deleted from the 
target file. If the resource does not exist in the target file then this bit 
will be ignored. 
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Resource Type 
The Resource Type field (4 bytes) specifies the resource type of the 
resource. 


Source ID 
The Source ID field (2 bytes) specifies the resource id in the source file. 
Ignored if find by id (bit 1) is O or if copy (bit 13) is 0. 


Target ID 
The Target ID field (2 bytes) specifies the resource id in the target file. 
Ignored if find by id (bit 1) is 0. 


CRC/Version 
The CRC/Version field (2 bytes) is not used and should be specified as 
zero. 


Filler 
The Filler1 field (2 bytes) is not used and should be specified as zero. 


Filler2, RDelsize and RAddsize 
The Filler2, RDelsize and RAddsize fields (4 bytes each) are used 
internally and should be specified as zero. 


Resource Name 

The Resource Name field is an even-padded Pascal string that gives the 
name of the resource. It must be non-empty if find by id (bit 1) is 0. To 
help insure that the correct resource is being installed, the name of the 
resource in the source file must match this field if the field is non-empty (it 
will match if find by id (bit 1) is 0). Also the name of the resource in the 
target file must match unless no old name (bit 7) is 1. 


Previous CRC List 
The Previous CRC List field (2 bytes) is currently unused and should be 
specified as zero. 


Disk Blocks List 
The Disk Blocks List field is currently unused and should be specified as zero. 


Notes 
e The high order nibble of the File or Resource Spec Flags field can be thought of 
as an opcode. Typical values are: 
$E — Ifthe user clicks Install then delete the file or resource from the target disk 
and copy over the file or resource from the source disk. If the user clicks 
Remove then delete any file or resource. 
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$C — If the user clicks Install or Remove delete the file or resource from the 
target disk. 

$6 -— If the user clicks Install then delete the file or resource from the target disk 
and copy the file or resource from the source disk. (This spec is ignored if 
the user clicks Remove.) 

$4 — Ifthe user clicks Install then delete the file or resource from the target disk. 
(This spec is ignored if the user clicks Remove.) 

¢ If copy (bit 13) is 1 then the delinst (bit 14) should also be specified as 1. 

e Ifa file exists on the target disk and its creation date is greater than or equal to the 
creation date of the file on the source disk then copy (bit 13) and delinst (bit 14) 
are ignored and taken as 0. 

¢ The Installer performs very poorly on single-drive systems. This is expected to be 
improved. 

Files: 

¢ Ifa file is to have both forks deleted then the whole file is deleted, otherwise just 
the appropriate fork is truncated. 

¢ Finder comments are not copied. This may be changed in the future. 

e Ifa file exists on the target disk and its creation date is greater than or equal to the 
creation date of the file on the source disk then copy (bit 13) and delinst (bit 14) 
are ignored and taken as 0. 

Resources: 

e Copying or deleting a resource that owns other resources (i.e. a DRVR) causes 
the owned resources to be copied or deleted too. The owned resources should 
not be mentioned in the script. In addition to norma! ownership (see the Resource 
Manager chapter of Inside Macintosh), the Installer “knows” that resource DRVR 9 
“ MPP” owns DRVR 10 *.ATP” and NBPC 1 and 2. 

e When DRVRs with IDs greater than or equal to 12 may be renumbered. Any 
owned resources will also be renumbered (and internal references changed). 

e Resource Specs which are only to delete resources (i.e. copy (bit 13) is 0) must be 
associated with a source file but do not have to exist in the source file. 

e There is currently no version checking for resources. This may be changed in the 
future. It is expected that version numbers will begin at offset 4 in the resource 
and consist of the resource type (4 bytes), id (2 bytes) and an unsigned integer 
specifying the version (2 bytes). Not all resource types can have the type in this 
position. For DRVRs the same information follows the driver name on the next 
even byte boundary (and the id is ignored). Support for other resources may be 
added in the form of CRCs. 

e If you're installing FONDs, then the installer will also install a FONT resource of 
point size 0 and add the FONTs that are in the FOND's font association table. 
Note: FONTs should not be mentioned explicitly in the installer script. FONDs 
cannot be deleted by an installer script. 

ResEdit: 

e If you use ResEdit to create a script, you must make sure yourself that the number 
of characters in a help field is even—ResEdit will not do this for you. You can do 
this by doing a Get Info on the help field, and, if the length is odd, adding a space 
to the help field. 
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Example Script 


The following is the RMaker input for an example script. 


* example script 
script 


type insc = GNRL 


f 
x Script Format 


-H 

0000 

* Script Flags 
~H 

0000 

* Script Name 
P 

Example Script 
* even pad 

-H 

00 
* Script Help 
-I 

78 
S 

This is just an example script. It copies\20 
one file and two System Resources.\20 

* even pad 

* File List 

x Number of Files 

me i 

1 

* File Spec 

* File Spec Flags 


H 

E037 

* File Type 

S 

MYTP 

* File Creator 
eS 

MYCR 

* Creation Date 
-H 

SABCDEF1 

* Handle, FDelsize, FAddsize 
-H 

00000000 

00000000 

00000000 

* File Name 

-P 

My File 

a even pad 
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* Resource File List 

x Number of Target Files 
-I 

1 

x Target File Spec 

* File Spec Flags 


-A 

0003 

i Type 

5 

MYTP 

* Creator 

-S 

MYCR 

* Creation Date (ignored) 


„H 

00000000 

* Handle, FDelsize, FAddsize 
~H 

00000000 

00000000 

00000000 

* File Name 

aP 

System 

* even pad 

~H 

00 

* Source File List 

* Number of Source Files 
oak 

l 

* Source File Spec 

* File Spec Flags 


eH 

0003 

k File Type 

.S 

ZSYS 

* File Creator 
“> 

MACS 

* Creation Date 


sH 
00000000 
* Handle, FDelsize, FAddsize 


sH 

00000000 
00000000 
00000000 

* File Name 
= 

system 

* even pad 
-H 
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00 


* Resource List 


Number of Resources 


ee 2 

2 

* Resource Spec 
Resource Spec Flags 
sH 

E042 

* Resource Type 

-S 

RSRC 

* source ID 

eL 

128 

= Target ID 

et 

128 

k CRC/Version 

.H 

0000 

* Filleri, Filler2 
-H 

0000 

00000000 

* RDelsize, RAddsize 
fe 

00000000 

00000000 

* Resource Name 

yg 

rsrc name 

a even pad 

* Previous CRC List 
ou 

0 

* Resource Spec 

= Resource Spec Flags 
eH 

E040 

* Resource Type 

5 

DRVR 

i Source ID (ignored) 
Ti 

0 

x Target ID (ignored) 
I 

0 

k CRC/Version 

.H 

0000 

* Fillerl, Filler2 
H 

0000 
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00000000 


a RDelsize, RAddsize 
~H 

00000000 

00000000 

* Resource Name 

»P 

My Desk Accessory 

* even pad 

* Previous CRC List 
cl 

0 

* Disk Blocks 

ol 

0 


1 An even-padded Pascal string contains a length byte followed by that many 
characters followed by a pad byte if necessary to make the total length (including 
the length byte and pad byte) even. 


2 An even-padded word-counted string contains a length word followed by that 


many characters followed by a pad byte if necessary to make the total length 
(including the length word and pad byte) even. 
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#76: The Macintosh Plus Update Installation Script 
see also: Technote #75 —The Installer and Scripts 


Written by: scott Douglass February 24, 1986 


This technote describes what the Macintosh Plus Update installation script 
installs. 


This information applies to the Macintosh Plus Update installation scripts on the disks 
System Tools version 1.0 and 1.1 and System Installation version 1.0 (the latter two 
scripts are the same). 


The Macintosh Plus Update installation script is designed to update System files so that 
they run on both Macintoshes and Macintosh Pluses. The intent is to change existing 
System files into Macintosh Plus System Files without disturbing user-installed fonts, 
desk accessories and such. 


The following files are copied from the Installer’s disk to the System Folder of the target 
disk when the user clicks Install. The files are replaced only if their creation dates 
warrant — that is, if the creation date of the file on the target disk is earlier that the 
creation date of the file on the Installer’s disk). If the target disk is an HFS volume, the 
target files must be in the root or System Folder to be found (they must be in the root 
under Hard Disk 20 Startup version 1.0). 


e the data fork of the System File (The new data fork includes the check for 
installation of ram-based Hard Disk 20 when booting on 64K ROMs. The ROM 
patches are now loaded from resources PTCH with the same id as the ROM 
version number.) 


¢ the files Finder, ImageWriter, AppleTalk ImageWriter, LaserWriter, Laser Prep 
and Font/DA Mover, if they were already present 


The following resources are removed, if present, from the System file of the target disk. 
when the user clicks Install (or Remove on System Tools v1.0): 


¢ PAPA -8192 (Under the new Chooser, this Same resource is now found in each 
printer driver file that has named printers.) 


e the Choose Printer desk accessory 


e INIT6 (The new AppleTalk drivers do not benefit from its presence.) 
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The following resources are copied from the System file on the Installer’s disk to the 
System file of the target disk when the user clicks Install: 


e the Chooser and Control Panel desk accessories 


e the Key Caps, Scrapbook, Alarm Clock and Calculator desk accessories, if they 
were already present 


¢ ALRT -3994, -3995, -3996 and -3997; DITL -3999 and -4000; DLOG -3999 and 
-4000 (These resources are used by PACK 3 (Standard File) and they do not 
have proper owned IDs.) 

¢ CDEF 0 and 1 

* DRVR 2 *.Print” 

¢ DRVR 9 *.MPP” and 10 “.ATP” and NBPC 1 and 2 (AppleTalk) 

¢ FKEY 3 and 4 


¢ INIT O ( keyboard mapping), 1 (keypad mapping), 2 (user alerts), “Q” 
(MiniFinder), 13 (".Print" patch) and 35 (cache startup) 


e CACH 1 (Cache code — only effective on 128K ROMs) 

e LDEF 0 (A useful List Manager defproc.) 

e MDEF 0 (Scrolling menus — works on both 64K and 128K ROMs.) 

e PACK 0 (List Manager), 2 (Disk Initialization), 3 (Standard File), 4 (Floating 
Point), 5 (Transcendental Functions), 6 (International Utilities) and 7 (Binary to 


Decimal Conversion) 


¢ PTCH 105 (=$0069, for 64K ROMs), 117 (=$0075, for 128K ROMs) and 28927 
(=$70FF, for MacWorks) (These are the new system patches.) 


e STRO (This is the System file version string.) 

e WDEF 0 and1 (Zoom box variant on 128K ROMs.) 
The following resources are copied from the System file on the Installer’s disk to the 
System file of the target disk when the user clicks Install (but only with the installation 


script on System Tools version 1.1 and System Installation 1.0): 


¢ DSAT 0 (the message “Disassembler installed.” changed to “Using External 
Drive.”) 


- INIT 31 (the INIT init) 
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Other Notes: 
e There is currently no version checking for resources. 


¢ All owned resources are also installed or removed. See the Resource Manager 
chapter of Inside Macintosh for a definition of “owned”. 
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#77: HFS Ruminations 


See also: The File Manager (Beta Draft) 
Technical Note #66—Determining Which File System is 
Active 
Technical Note #67—Finding the “Blessed Folder” 
Technical Note #68—Searching All Directories on an HFS 
Volume 


Written by: Jim Friedlander June 7, 1986 





This Technical Note contains some thoughts concerning HFS. 





HFS numbers 


A drive number is a small positive word (e.g. 3). 
A vRefNum (as opposed to a WDRefNum) is a small negative word (e.g. SFFFE). 
A wDRe fNun is a large negative word (e.g. $8033). 


A DirID is a long word (e.g. 38). The root directory of an HFS volume always has a 
dirID of 2. 


Working Directories 


Normally an application doesn’t need to open working directories (henceforth wDs) 
using PBOpenWD, since SFGetFile returns a WDRefnun if the selected file is ina 
directory on a hierarchical volume and you are running HFS. There are times, however, 
when opening a w is desirable (see the discussion about Boot Drive below). 


If you do open a wD, remember that the system allocates space for a fixed number of 
wDs (currently 40) and that, unless you call PBCloseWD, WDs that you have created with 
a unique ioWDProcID (your creator bytes, for example) are only dealiocated when the 
system is rebooted. wDs created by the system are created with an ioWDProcID of 
‘ERIK’ ($45524948B) and are deallocated by the Finder. 


SFGetFile also creates WDs with an ioWDProcID of ‘ERIK’. If SFGetFile opens two 


files from the same directory (during the same application), it will only create one 
working directory. 
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There are no WORefnumns that refer to the root—the root directory of a volume is always 
referred to by a vRefNum. l 


When you can use HFS calls 


All of the new HFS 'H’ calls, except for PBHSet VInfo, can be made without regard to 
file system as long as you pass in a pointer to an HFS parameter block. PBHGetVol, 
PBHSetVol (see the warnings in the File Manager chapter of Inside Macintosh), 
PBHOpen, PBHOpenRF, PBHCreate, PBHDelete, PBHGetFinfo, PBHSetFinfo, 
PBHSetFLock, PBHRstFLock and PBHRename differ from their MFS counterparts only 
in that a dir ID can be passed in at offset $30. 


The only difference between, for example, PBOpen and PBHOpen is that bit 9 of the trap 
word is set, which tells HFS to use a larger parameter block. MFS ignores this bit, so it 
will use the smaller parameter block (not including the dirID). Remember that all of 
these calls will accept a WORefNum in the iovRefNun field of the parameter block. 


PBHGetVinfo returns more information than PBGetVInfo, SO, if you're counting on 
getting information that is returned in the HFS parameter block, but not in the MFS 
parameter block, you should check to see which file system is active. 


HFS-specific calls can only be made if HFS is active. These calls are: PBGet Cat Info, 
PBSetCatInfo, PBOpenWD, PBCloseWD, PBGetFCBInfo,PBGetWDinfo, PBCatMove 
and PBDirCreate. PBHSetVInfo has no MFS equivalent. If any of these calls are 
made when MFS is running, a system error will be generated. If PBCatMove or 
PBDirCreate are called for an MFS volume, the function will return the error code —123 
(wrong volume type). If PBGetCat Info or PBSetCat Info are called on MFS volumes, 
it’s just as if PBGetF Info and PBSetFInfo were called. 


Default volume 


If HFS is running, a call to Get vol (before you’ve made any SetVol calls) will return 
the WDRefNum of your application’s parent directory in the vRefNum parameter. If your 
application was launched by the user clicking on one or more documents, the 
wDRefNums of those documents’ parent directories are available in the vRefNum field of 
the AppFile record returned from GetAppFiles. 


If MFS is running, a call to GetVol (before you’ve made any Set Voi calls) will return 
the vRefNum of the volume your application is on in the vRefNum parameter. If your 
application was launched by the user clicking on one or more documents, the vRefNum 
of those documents’ volume are available in the vRefNum field of the AppFile record 
returned from GetAppFiles. 
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BootDrive 


If your application or desk accessory needs to get the WDRefNum of the “blessed folder” 
of the boot drive (for example, you might want to store a configuration file there), it can 
not rely on the low-memory global BootDrive (a word at $210) to contain the correct 
value. If your application is the startup application, BootDrive will contain the 
WDRefNum of the directory/volume that your application is in (not the WDRefNum of the 
“blessed folder”); Your application could have been Launched from an application that 
has modified BootDrive; If you are a desk accessory, you might find that some 
applications alter BootDrive. 


To get the “real” WORefNum of the “blessed folder” that contains the currently open 
System File, you can do something like this (Note: if you are running under MFS, 
BootDrive always contains the vRefNum of the volume on which the currently Mi 
System File is located): i 


CONST 
SysWDProcID = $4552494B; {“ERIK”)} 
BootDrive = $210; {address of Low-Mem global BootDrive} 
FSFCBLen = S3F6; {address of Low-Mem global to 
distinguish file systems } 
SysMap = SA58; {address of Low-Mem global that contains 
system map reference number} 
TYPE 
WordPtr = “Integer; {Pointer to a word(2 bytes) } 


FUNCTION HFSExists: BOOLEAN; 
Begin {HFSExists} 


HFSExists := WordPtr(FSFCBLen)* > 0; 
End; {HFSExists} 


FUNCTION GetRealBootDrive: INTEGER; 


VAR 
MyHPB : HParamBlockRec; 
MyWDPB : WDPBRec; 
err : OSErr; 
sysVRef : integer; {will be the vRefNum of open system’s vol} 


Begin {GetRealBootDrive} 
if HFSExists then Begin {If we’re running under HFS... } 


{get the VRefNum of the volume that } 


{contains the open System File } 
err:= GetVRefNum(WordPtr (SysMap) *,sysVRef) ; 
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with MyHPB do Begin 
{Get the “System” vRefNum and “Blessed” dirID} 
ioNamePtr := NIL; 


ioVRefNum := sysVRef; {from the GetVrefNum call} 
ioVolIndex = 0; 
End; {with} 


err := PBHGetVInfo(@MyHPB, FALSE); 


with myWDPB do Begin {Open a working directory there} 
ioNamePtr := NIL; 
ioVRefNum >= sysVRef; 
ioWDProcID = SysWDProcID; {Using the system proc ID} 


ioWDDirID := myHPB.ioVFndrinfo[1];{ see TechNote 67} 
End; {with} 
err := PBOpenWD (@myWDPB, FALSE); 


GetRealBootDrive := myWDPB.ioVRefNum; 
{We've got the real WD} 
End Else {we're running MFS} 
GetRealBootDrive := WordPtr(BootDrive)”%; 
{BootDrive is valid under MFS} 
End; {GetRealBootDrive} 


The Poor Man’ rch Path (PMSP 


lf HFS is running, the PMSP is used for any file system call that can return a file-not- 
found error, such as PBOpen, PBClose, PBDelete, PBGetCat Info, etc. It is not used 
for indexed calls (that is, where ioFDirIndex is positive) or when a file is created 
(PBCreate) or when a file is being moved between directories (PBCatMove). The PMSP 
is also not used when a non-zero dirID is specified. 


Here’s a brief description of how the default PMSP works. 


1) The directory that you specify (specified by WORefNum or pathname) is searched; if 
the specified file is not found, then 


2) the volume/directory specified by BootDrive (low-memory global at $210) Is 
searched IF it is on the same volume as the directory you specified (see #1 above); if 
the specified file is not found, or the directory specified by BootDrive is not on the 
same volume as the directory that you specified, then 


3) if there is a “blessed folder’ on the same volume as the directory you specified (see 
#1 above), it is searched. Please note that if #2 above specifies the same directory as 
#3, then that directory is not searched twice. If no file is found, then 


4) fnfErr is returned. 
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ioDirld and ioFiNum 


Two fields of the HParamBlockRec record share the same location. ioDirID and 
{oF 1Num are both at offset $30 from the start of the parameter block. This causes a 
problem, since, in some calls (e.g. PBGetCatInfo), A dirID is passed in and a file 
number is returned in the same field. 


Future versions of Apple's HFS interfaces will omit the ioF1Num designator, so, if you 
need to get the file number of a file, it will be in the ioDirID of the parameter block 
after you have made the call. If you are making successive calls that depend on 
ioDirID being set correctly, you must “reset” the ioDirID field before each call. The 
program fragment in Technical Note #68 does this. 


PBHGetVinf 


Normally, PBHGetVInfo will be called specifying a vRefNum. There are times, 
however, when you may make the call and only specify a volume name. If this is so, 
there are a couple of things to look out for. 


Let's say that we have two volumes mounted: “vol1:” (the default volume) and 
“7o12:”. We also have a variable of type HParamBlockRec called MyHPB. We want to 
get information about vol2:, so we put a pointer to a string (let’s call it £Name) in 
MyHPB.ioNamePtr. The string fName is equal to “vol2” (Please note the missing 
colon). We also initialize MyHPB.ioVRefNum to 0. Then we make the call. We are very 
surprised to find out that we are returned an error of 0 (noErr) and that the iovRefNum 
that we get back is not the vRefNum of Vol12:, but rather that of Vol1:. 


Here’s what's happening: PBHGet VInfo looks at the volume name, and sees that it is 
improper (it is missing a colon). So, being a forgiving sort of call, it goes on to look at 
the iovRefNum field that you passed it (see pp. 99 of Inside Macintosh—Volume If. lt 
sees a 0 there, so it returns information about the default volume. 


if you want to get information about a volume, and you just have its name and you are 
not sure that the name is a proper one, you should set MyHPB.ioVRefNum to —32768 
($8000). No vRefNum or WDRefNum Can be equal to $8000. By doing this, you are 
forcing PBHGet VInfo to use the volume name and, if that name is invalid, to return a 
—35 error (nsvErr), “No such volume”. 


PBGetWDiInfo and Register D1 


There was a problem with PBGet WDInfo that sometimes caused the call to inaccurately 
report the dirID of a directory. It is now fixed in System 3.2 (which most users should 
now be running). To be absolutely sure that you won't get stung by this, clear register 
D1 (CLR.L D1) before a call to PBGetWDInfo. You can do this either with an INLINE 
(Lisa Pascal and most C’s) or with a short assembly-language routine before the call to 
PBGetWDInfo. 
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#78: Resource Manager Tips 

See also: The Resource Manager 
The Memory Manager 
The Menu Manager 


Written by: Jim Friedlander June 8, 1986 





This Technical Note discusses some minor problems with the Resource 
Manager and how to work around them. 





OpenResFile Bug 


Programmers must exercise care when calling OpenResFile with a file name that has 
been obtained from a resource. The 64K ROM was patched to accommodate some 
older applications that had trouble finding the print drivers. The patch attempts to 
determine whether the string passed as a parameter to OpenResFile is the name of the 
printer by inspecting the high bits of the pointer, of which bit 5 of the high byte will be set 
if the pointer is a dereferenced master pointer of a resource. Due to this patch, the 
following code will cause a System Error 2 (address error): 


TYPE 
whichFile = Record 
myFileType: longint; 
name: Str255; 
End; {TYPE whichFile} 
pWhichFile = “whichFile; 
hWhichFile = *pWhichFile; 
VAR 
myH: hWhichFile; 
resRefNum: integer; 
Begin 


{allocate relocatable object} 

MyH:= hWhichFile (NewHandle (SizeOf (whichFile) )); 

MyH** .myFileType:= 1; {something odd, will generate address error} 

AddResource (handle (myH), 'FOO ',0); {make it a resource} 

MyH**.name:= "Watch me die’; {pointer to MyH**.name has the 
resource bit set} 

HLock (handle (myH) ) ; (OpenResfile can cause relocation} 

resRefNum:= OpenResFile (myH**.name) ; 

{this will crash in RecoverHandle} 


HUnLock (handle (myH) ); 
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To avoid this problem, mask off the high byte of the pointer with something like: 


ResRefNum:= OpenResFile (StringPtr (BitAnd (ord4 (@myH**.name), SOOFFFFEFF) )“); 
{for Pascal} 


or 
ResRefNum = OpenResFile((long) (**MyH).name & OxOOFFFFFF); /* for C */ 


GetMenu and ResErrProc 


If your application makes use of ResErrProc (a pointer to a procedure stored in 
low-memory global $AF2) to detect resource errors, you will get unexpected calls to 
your ResErrProc procedure when calling GetMenu on 128K ROMs. The Menu 
Manager call GetMenu makes a Call to GetResInfo, requesting resource information 
about MDEF 0. Unfortunately, ROMMapInsert is set to FALSE, so this call fails, setting 
ResErr to —192 (resNotFound). This in turn will cause a call to your ResErrProc, 
procedure even though the GetMenu call has worked correctly. This is only a problem 
if you are using ResErrProc. 


The workaround is to: 

1) save the address of your ResErrProc procedure 

2) clear ResErrProc 

3) do a Get Resource call on the MENU resource you want to get 

4) check to see if you get a nil handle back, if you do, you can handle the error in 
whatever way is appropriate for your application 

5) call GetMenu, and 

6) when you are done calling GetMenu, restore ResErrProc 


SetResAtirs on read-only resource maps 


SetResAttrs does not return an error if you are setting the resource attributes of a 
resource in a resource file that has a read-only resource map. The workaround is to 
check to see if the map is read-only and proceed from there: 


CONST 
MapROBit = 8; {Toolbox bit ordering for bit 7 of low-order byte} 


Begin 


attrs:= GetResFileAttrs (refNum) ; 
If BitTst (@attrs,MapROBit) then ...{write-protected map} 
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#79: ZoomWindow 
See also: Technical Note #57—Macintosh Plus Overview (p. 7) 


Written by: Jim Friedlander June 7, 1986 





This Technical Note contains some hints about using ZoomWindow. 





ZoomWindow allows a window to be toggled between two states (“state” means size and 
location), a default state and a user-selectable state. The default state stays the same 
unless the application changes it. The user-selectable state is altered when the user 
changes the size or location of a “zoomable” window. The code to handie zoomable 
windows in the main event loop would look something like this: 


CASE myEvent.what of 
mouseDown: Begin 
partCode:= FindWindow (myEvent .where, whichWindow} ; 
CASE partCode of 
inSysWindow: ...; {and so on} 
inZoomIn, InZoomOut : 
If TrackBox (whichWindow, myEvent .where, partCode) 
then ZoomWindow (whichWindow, partCode, TRUE) ; 
{and so on} 


lf a window is “zoomable’, that is, if it has a window definition ID of 8 (using the standard 
WDEF), WindowRecord.DataHandle will point to a structure that consists of two 
rectangles. The user-selectable state is stored in the first rectangle, the default state is 
stored in the second rectangle. Your application can modify either one of these states, 
though modifying the user-selectable state might present a surprise to the user when 
the window is zoomed from the default state. You should also be careful to not change 
either rectangle so that the title bar of the window will be hidden by the menu bar. 


Before you modify these rectangles, you must make sure that DataHandle is not nil. If it 
is nil for a window with window definition ID of 8, that means that the program is not 
executing on a system/machine that supports zooming windows, such as a 64K ROM 
machine, or a 128K ROM machine with a System File earlier than version 3.0. | 


Please note that you need not be concerned about the use of a window with window 
definition 1D 8 making your application machine-specific—if the hardware/System that 
your application is running on doesn’t support zooming windows, FindWindow will 
never return inZoomIn Or inZoomOut, so the new ROM calls TrackBox and 
ZoomWindow will never be called. 
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lf DataHandle is not nil, you can set the coordinates of either rectangle, e.g. the Finder 
sets the second rectangle (default state) so that a “zoomed-out” window wiil not cover 


the disk and trash icons. 


Note: ZoomWindow assumes that the window that you are zooming is the current 
GrafPort, which it usually is, since you can only zoom the active window. If your 
application is written such that this is not always the case, you should do something like 


the following: 


CASE myEvent.what of 


mouseDown: Begin 
partCode:= FindWindow (myEvent .where, whichWindow) ; 


CASE partCode of 


inSysWindow: ...; {and so on} 

inZoomIn, InZoomOut : hn 
If TrackBox(whichWindow,myEvent.where,partt- } 
then Begin 


GetPort (OldPort); {save current port} 
SetPort (whichWindow) ; 
ZoomWindow (whichWindow, partCode, TRUE) ; 
SetPort (OldPort); {restore port} 
End; {If TrackBox...} 
{and so on} 


If thePort is not set to the window that is being zoomed, an address error will be 
generated. 
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#80: Standard File Tips 
See also: The Standard File Package 


Written by: Jim Friedlander June 7, 1986 





Here are some quick tips about using Standard File. 





SFSaveDisk and CurDirStore 





Low-memory location $214 (SFSaveDisk—a word) contains —1* the vRefNum of the 
volume that SF is displaying (MFS and HFS). It never contains —1* a WDRefNum. 


Low-memory location $398 (CurDirStore—a long word) contains the dirID of the 
directory that SF is displaying (HFS only). 


This information can be particularly useful at hook time, when the vRefNum field of the 
reply record has not yet been filled in. Note: reply. fName is filled in correctly at hook 
time if a file has been selected. If a directory has been selected, reply.fType is 
non-zero (it contains the dir1D of the selected directory). If neither a file nor a directory 
is selected, both reply. fName[0] and reply.fType are 0. 


tting Standard File’ fault volume and director 
If you want SFGetFile or SFPutFile to display a certain volume when it draws its 
dialog, you can put —1 * the vRefNum of the volume you wish it to display into the 


low-memory global SFSaveDisk (a word at $214). 


In Pascal, you would use something like: 


TYPE 


WordPtr = “integer; {Pointer to a two-byte location} 
CONST 

SFSaveDisk = $214; {Location of low-memory global} 
VAR 

SFSaveVRef : WordPtr; 


myVRef : integer; 


Technical Note #80 page 1 of2 Standard File Tips 


Begin ... 
{myVRef gets assigned here} 


SFSaveVRef:= POINTER(SFSaveDisk); {Point to SFSaveDisk} 


SFSaveVRef*:= -1 * myVRef; {“stuff” the value in} 
SFPGetFile(... 


In C you would do something like this (where a variable of type “short” occupies 2 
bytes): 


#define SFSaveDisk *(short *)0x214 
short myVRef; 
{myVRef gets assigned here} 


SFSaveDisk = -1 * myVRef; /* “stuff” the value in */ 
SFGetFile(... 


If you are running HFS and would like to have Standard File display a particular 
directory as well as a particular volume, you can’t just put a WDRefNum into 
SFSaveDisk. If you do put a WORefNum into SFSaveDisk, Standard File will display the 
root directory of the default volume. Instead, you must put -1 * the vRefNum into 
SFSaveDisk (see above) and put the dirID of the directory that you wish to have 
displayed in CurDirStore. If you put an invalid dirID into CurDirStore, Standard 
File will display the root level of the volume referred to by SFSaveDisk. To change 
CurDirStore you can use a technique similar to the above, but remember that 
CurDirStore is a four-byte value. If your application is running under MFS, Standard 
File ignores CurDirStore, so you can use the same code regardless of file system. 


tandar il n eaqmentati 


If your application makes use of Standard File dialog hooks, file filters and event filters, 
make sure that all these related routines are in the same segment. 


lf you have different calls to Standard File in different segments, make sure that the 
appropriate hooks and filters are in the same segment as the call to Standard File. 


lf hooks and/or filters are in different segments from the call(s) to Standard File, strange 
and unpredictable, but not wonderful, things may happen. 
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#81: Caching 
See also: File Manager 

Device Manager 

Technical Note #14—The INIT 31 Mechanism 
Written by: Rick Blair June 17, 1986 


This Technical Note describes disk and File System caching on the 
Macintosh, with particular emphasis on the high-level File System cache. Of 
the three caches used for file 1/O, this is the one which could have the most 
impact on your program. Note: This big File System cache is only available 
on 128K ROM machines. 


A term 


In this note | will use the term “HFS” to mean the Hierarchical File System and the 
newer Sony driver which can access the 800K drives. Both RAM-based HFS (Hard Disk 
20 file) and the 128K ROM version include the second-generation Sony driver. 


There’ Iw he (t 1 


The first type of cache used by the File System has been around since the days of the 
Macintosh File System. Under MFS, each volume has a one-block buffer for all 
file/volume data. This prevents a read of two bytes followed by a read (at the next file 
position) of 4 bytes from causing actual disk I/O. The volume allocation map also gets 
saved in the system heap but it’s not really part of the cache. 


This type of caching is still used by HFS, which includes MFS-format volumes which 
may be mounted while running HFS. With HFS, the cache is a little bigger: each volume 
gets 1 block of buffering for the bitmap, 2 blocks for volume (including file) data, and 16 
blocks for HFS B*-tree contro! buffering. 


This cache lives in the system heap (unless HFS is using the new File System caching 
mechanism, in which case things become more complicated. See “type 3” below). 


he track fever (t 
The track cache, only present with the enhanced Sony driver, will cache the current 
track (up to twelve blocks) so that subsequent reads to that track may use the cache. 


The track cache is “write through”; all writes go to both the cache and the Sony disk so 
flushing is never required. 
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Track caching only takes place for synchronous I/O calls; when an application makes 
asynchronous calls it expects to use the time while the disk is seeking, etc. to execute 
other code. 


The track cache gets its storage space from the system heap. 
h f t 


The last type of cache to be discussed is only available under the 128K Macintosh Plus 
ROMs. This user-controlled cache is not “write-through”. 


Based on how much space the user has allocated via the control panel, the File System 
will set up a cache which can accommodate a certain number of blocks. This storage 
will come from the application heap in the space above BufPtr (see technote #14 and 
below). This is really the space above the jump table and the “as world”, not technically 
part of the application heap. However, moving BufPtr down will cause a 
corresponding reduction in the space available to the application heap. 


The installation code will also grab the space used by the old File System cache (type 
1) since all types of disk blocks can be accommodated by this new cache. 


The bulk of the caching code used for this RAM cache is also loaded above BufPtr at 
application launch time. This is accomplished by the INIT 35 resource which is installed 
in the system heap and initialized at boot time. At application launch time, INIT 35 
checks the amount of cache allocated via the control panel and moves BufPtr down 
accordingly before bringing in the balance of the caching code. The RAM caching code 
is in the CACH 1 resource in the System File. 


The caching code always makes sure there is room for 128K of application heap and 
32K of cache. If the user-requested amount would reduce the heap/cache below these 
values then the cache space is readjusted accordingly. 


Up to 36 separate files may be buffered by the cache. Each queue is a list of blocks 
cached for that file. Information is kept about the “age” of each block and the blocks are 
also kept in a list in the order in which they occur in the file. The aging information tells 
which blocks were Least Recently Used; these are the first to be released when new 
blocks become eligible for caching. The file order information is useful for flushing the 
cache to the disk in an efficient manner, i.e. the file order approximates disk order. 


Assuming this cache has been enabled by the user, all files which are read from or 
written to by File System (HFS) calls are subject to caching under the current 
implementation. The cache is not “write through” like the track cache. When a File 
System write (PBWrite, WriteResource, etc.) is done the block is buffered until the 
block is released (age discrimination), a volume flush is done or the application 
terminates. 


It may be useful to an application to prevent this process of reading and writing “in 
place”. The Finder disables caching of newly read/written blocks while doing file copies 
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since it would be silly to cache files that the Finder was reading into memory anyway. 
Copy protection schemes may also need this capability. Disabling reading and writing 
in place is accomplished by setting a bit in a low memory flag byte, CacheCom (see 
below). When you set this flag, no new candidates for caching will be accepted. Blocks 
already saved may still be read from the cache, of course. 


CacheCom is at $39C. Bit 7 is the bit to set to disable subsequent caching, as follows: 


MOVE.B CacheCom, savetemp ;Save away the old value 
BSET #7,CacheCom ;tell caching code to stop R/W I.P. 


BTST savetemp 


BNE.S @69 
BCLR #7,CacheCom ;only clear it if it was cleared before 
@69 


Bit 6 contains another flag which can force all 1/O to go to the disk. If that flag is set then 
every time even one byte is requested from the File System the disk will be hit. | can 
think of no good reason to use this except to test the system code itself. The other bits 
should likewise be left alone. 


Please don't use this feature unnecessarily; the user should retain control over caching. 
Important: if your program doesn’t have enough space to run due to caching you 
should ask the user to disable (or reduce) it with the control panel and then relaunch 
your application. This may be the subject of a future technote. 


BufPtr 


The RAM-resident caching software arbitrates BufPtr in the friendliest manner 
possible. It saves the old value away before changing it, and then when it is time to 
release its space it looks at it again. If BufPtr has been moved again, it knows that it 
can’t restore the old value it saved until BufPtr is put back to where it left it. In this 
manner any subsequent code or data put up under BufPtr is assured of not being 
obliterated by the caching routines. 
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#82: TextEdit: Advice & Descent 


See also: TextEdit 
Technical Note #22—TEScroll Bug on Macintosh Plus 
Technical Note #57—Macintosh Plus Overview 


Written by: Rick Blair | June 21, 1986 


This Technical Note will point out some bugs (and possible workarour ~s), 
some differences between the 128K and 64K ROM versions of TextEd: “8 d 
other items of interest for the TextEdit programmer. 


election rectanal 


Multiple line selections are often more complex shapes than simple rectangles. If this is 
the case, the teSelRect field of the TERec is set to the last (bottommost) rectangle in 
the selection. The teHiHook is called to invert each line of the selection. 


The 128K ROM version limits the selection range (i.e. the lines that get set into 
teSelRect) to only those lines which will fit into the viewRect. The 64K ROM made all 
the calls for the complete selection and just let clipping take care of the rest. This means 
that on the 128K ROMs teSelRect will be left at the last visible line. 


TEDoText 


The parameters of this special hook into TextEdit need a little additional explanation. D3 
and D4 are described on page I-391 as being the first and last characters to be redrawn. 
This is true but specific to the -1 “DoDraw” case. In fact all the calls to TEDoText are 
interested in these first and last character positions. They determine the selection for a 
(1) highlight call, the caret position for a (-2) DoCaret call (where D4 is ignored as it’s 
assumed to equa! D3), etc. 


Note that the (-2) DoCaret call behaves differently on the 128K ROM. Good old I-391 
says it sets up the pen position for caret drawing; it did this on the 64K ROMs. Since an 
InvertRect call is used to draw the caret if you use the default teCarHook, the 128K 
ROM just sets up teSelRect, it doesn’t bother with the QuickDraw pen. 


TEScerpLength 


Inside Macintosh describes TEScrpLength as a long integer; indeed, four bytes are 
reserved for this value with the intent of someday using that range of values. However, 
both the 128K and 64K ROMs use word operations in their accesses to TEScrpLength 
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and make word calculations with it. This means that the high word of TEScrpLength Is 
used for calculations. This is something to watch out for. 


CharWidth 


Inside Macintosh says that CharwWidth takes into account stylistic variations in 
determining the width of a character. In fact for italic and outlined styles the extra width 
is not taken into account. TextEdit relies on Charwidth for positioning of the caret, etc. If 
you have chosen to use, for instance, italic style in your TE record you will find that as 
you type the caret actually overlaps the character to the left and so when the caret is 
erased some of that character will get erased, too. This is somewhat disconcerting to the 
user but the program will still function correctly. 


lik 


lf you add your own click loop and try to do something like update scroll bars you may 
run into trouble. Before your routine gets called, TextEdit will have set clipping down to 
just the viewRect. You will have to save away the old clipping region, set it out to 
sufficient size (-32767, -32767, 32767, 32767 is probably OK), do your drawing, then 
restore TextEdit’s clipping area so that it can function properly. 
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#83: System Heap Size Warning 
See also: The Memory Manager 


Written by: = Jim Friedlander June 21, 1986 





The size of the System Heap will most likely change in the coming year. In order to 
accommodate some applications, the size of the System Heap decreased on 128K 
ROM machines while low-memory global! and trap table space increased. If your 
application relies on the Application Heap Starting in a particular place, you should 
change this. The low-memory global ApplZone (a long word at $2AA) contains a 
pointer to the current heap zone. The high-level call ApplicZone returns the contents 
Of Appl Zone. 


If your application assumes that the Application Heap will always start at $cB00, your 
application will break when the size of the System Heap changes. 
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